style: format all files with prettier

This commit is contained in:
Seth Hobson
2026-01-19 17:07:03 -05:00
parent 8d37048deb
commit 56848874a2
355 changed files with 15215 additions and 10241 deletions

View File

@@ -21,19 +21,20 @@ Comprehensive patterns for creating, maintaining, and managing Architecture Deci
### 1. What is an ADR?
An Architecture Decision Record captures:
- **Context**: Why we needed to make a decision
- **Decision**: What we decided
- **Consequences**: What happens as a result
### 2. When to Write an ADR
| Write ADR | Skip ADR |
|-----------|----------|
| New framework adoption | Minor version upgrades |
| Database technology choice | Bug fixes |
| API design patterns | Implementation details |
| Security architecture | Routine maintenance |
| Integration patterns | Configuration changes |
| Write ADR | Skip ADR |
| -------------------------- | ---------------------- |
| New framework adoption | Minor version upgrades |
| Database technology choice | Bug fixes |
| API design patterns | Implementation details |
| Security architecture | Routine maintenance |
| Integration patterns | Configuration changes |
### 3. ADR Lifecycle
@@ -58,6 +59,7 @@ Accepted
We need to select a primary database for our new e-commerce platform. The system
will handle:
- ~10,000 concurrent users
- Complex product catalog with hierarchical categories
- Transaction processing for orders and payments
@@ -69,25 +71,28 @@ compliance for financial transactions.
## Decision Drivers
* **Must have ACID compliance** for payment processing
* **Must support complex queries** for reporting
* **Should support full-text search** to reduce infrastructure complexity
* **Should have good JSON support** for flexible product attributes
* **Team familiarity** reduces onboarding time
- **Must have ACID compliance** for payment processing
- **Must support complex queries** for reporting
- **Should support full-text search** to reduce infrastructure complexity
- **Should have good JSON support** for flexible product attributes
- **Team familiarity** reduces onboarding time
## Considered Options
### Option 1: PostgreSQL
- **Pros**: ACID compliant, excellent JSON support (JSONB), built-in full-text
search, PostGIS for geospatial, team has experience
- **Cons**: Slightly more complex replication setup than MySQL
### Option 2: MySQL
- **Pros**: Very familiar to team, simple replication, large community
- **Cons**: Weaker JSON support, no built-in full-text search (need
Elasticsearch), no geospatial without extensions
### Option 3: MongoDB
- **Pros**: Flexible schema, native JSON, horizontal scaling
- **Cons**: No ACID for multi-document transactions (at decision time),
team has limited experience, requires schema design discipline
@@ -99,6 +104,7 @@ We will use **PostgreSQL 15** as our primary database.
## Rationale
PostgreSQL provides the best balance of:
1. **ACID compliance** essential for e-commerce transactions
2. **Built-in capabilities** (full-text search, JSONB, PostGIS) reduce
infrastructure complexity
@@ -111,17 +117,20 @@ additional services (no separate Elasticsearch needed).
## Consequences
### Positive
- Single database handles transactions, search, and geospatial queries
- Reduced operational complexity (fewer services to manage)
- Strong consistency guarantees for financial data
- Team can leverage existing SQL expertise
### Negative
- Need to learn PostgreSQL-specific features (JSONB, full-text search syntax)
- Vertical scaling limits may require read replicas sooner
- Some team members need PostgreSQL-specific training
### Risks
- Full-text search may not scale as well as dedicated search engines
- Mitigation: Design for potential Elasticsearch addition if needed
@@ -200,6 +209,7 @@ Accepted (Supersedes ADR-0003)
ADR-0003 (2021) chose MongoDB for user profile storage due to schema flexibility
needs. Since then:
- MongoDB's multi-document transactions remain problematic for our use case
- Our schema has stabilized and rarely changes
- We now have PostgreSQL expertise from other services
@@ -219,11 +229,13 @@ Deprecate MongoDB and migrate user profiles to PostgreSQL.
## Consequences
### Positive
- Single database technology reduces operational complexity
- ACID transactions for user data
- Team can focus PostgreSQL expertise
### Negative
- Migration effort (~4 weeks)
- Risk of data issues during migration
- Lose some schema flexibility
@@ -231,6 +243,7 @@ Deprecate MongoDB and migrate user profiles to PostgreSQL.
## Lessons Learned
Document from ADR-0003 experience:
- Schema flexibility benefits were overestimated
- Operational cost of multiple databases was underestimated
- Consider long-term maintenance in technology decisions
@@ -249,6 +262,7 @@ improve auditability, enable temporal queries, and support business analytics.
## Motivation
Current challenges:
1. Audit requirements need complete order history
2. "What was the order state at time X?" queries are impossible
3. Analytics team needs event stream for real-time dashboards
@@ -257,13 +271,14 @@ Current challenges:
## Detailed Design
### Event Store
```
OrderCreated { orderId, customerId, items[], timestamp }
OrderItemAdded { orderId, item, timestamp }
OrderItemRemoved { orderId, itemId, timestamp }
PaymentReceived { orderId, amount, paymentId, timestamp }
OrderShipped { orderId, trackingNumber, timestamp }
```
### Projections
@@ -333,12 +348,12 @@ This directory contains Architecture Decision Records (ADRs) for [Project Name].
## Index
| ADR | Title | Status | Date |
|-----|-------|--------|------|
| [0001](0001-use-postgresql.md) | Use PostgreSQL as Primary Database | Accepted | 2024-01-10 |
| [0002](0002-caching-strategy.md) | Caching Strategy with Redis | Accepted | 2024-01-12 |
| [0003](0003-mongodb-user-profiles.md) | MongoDB for User Profiles | Deprecated | 2023-06-15 |
| [0020](0020-deprecate-mongodb.md) | Deprecate MongoDB | Accepted | 2024-01-15 |
| ADR | Title | Status | Date |
| ------------------------------------- | ---------------------------------- | ---------- | ---------- |
| [0001](0001-use-postgresql.md) | Use PostgreSQL as Primary Database | Accepted | 2024-01-10 |
| [0002](0002-caching-strategy.md) | Caching Strategy with Redis | Accepted | 2024-01-12 |
| [0003](0003-mongodb-user-profiles.md) | MongoDB for User Profiles | Deprecated | 2023-06-15 |
| [0020](0020-deprecate-mongodb.md) | Deprecate MongoDB | Accepted | 2024-01-15 |
## Creating a New ADR
@@ -384,6 +399,7 @@ adr link 2 "Complements" 1 "Is complemented by"
## ADR Review Checklist
### Before Submission
- [ ] Context clearly explains the problem
- [ ] All viable options considered
- [ ] Pros/cons balanced and honest
@@ -391,6 +407,7 @@ adr link 2 "Complements" 1 "Is complemented by"
- [ ] Related ADRs linked
### During Review
- [ ] At least 2 senior engineers reviewed
- [ ] Affected teams consulted
- [ ] Security implications considered
@@ -398,6 +415,7 @@ adr link 2 "Complements" 1 "Is complemented by"
- [ ] Reversibility assessed
### After Acceptance
- [ ] ADR index updated
- [ ] Team notified
- [ ] Implementation tickets created
@@ -407,6 +425,7 @@ adr link 2 "Complements" 1 "Is complemented by"
## Best Practices
### Do's
- **Write ADRs early** - Before implementation starts
- **Keep them short** - 1-2 pages maximum
- **Be honest about trade-offs** - Include real cons
@@ -414,6 +433,7 @@ adr link 2 "Complements" 1 "Is complemented by"
- **Update status** - Deprecate when superseded
### Don'ts
- **Don't change accepted ADRs** - Write new ones to supersede
- **Don't skip context** - Future readers need background
- **Don't hide failures** - Rejected decisions are valuable

View File

@@ -31,27 +31,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
### Added
- New feature X
## [1.2.0] - 2024-01-15
### Added
- User profile avatars
- Dark mode support
### Changed
- Improved loading performance by 40%
### Deprecated
- Old authentication API (use v2)
### Removed
- Legacy payment gateway
### Fixed
- Login timeout issue (#123)
### Security
- Updated dependencies for CVE-2024-1234
[Unreleased]: https://github.com/user/repo/compare/v1.2.0...HEAD
@@ -68,19 +75,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
[optional footer(s)]
```
| Type | Description | Changelog Section |
|------|-------------|-------------------|
| `feat` | New feature | Added |
| `fix` | Bug fix | Fixed |
| `docs` | Documentation | (usually excluded) |
| `style` | Formatting | (usually excluded) |
| `refactor` | Code restructure | Changed |
| `perf` | Performance | Changed |
| `test` | Tests | (usually excluded) |
| `chore` | Maintenance | (usually excluded) |
| `ci` | CI changes | (usually excluded) |
| `build` | Build system | (usually excluded) |
| `revert` | Revert commit | Removed |
| Type | Description | Changelog Section |
| ---------- | ---------------- | ------------------ |
| `feat` | New feature | Added |
| `fix` | Bug fix | Fixed |
| `docs` | Documentation | (usually excluded) |
| `style` | Formatting | (usually excluded) |
| `refactor` | Code restructure | Changed |
| `perf` | Performance | Changed |
| `test` | Tests | (usually excluded) |
| `chore` | Maintenance | (usually excluded) |
| `ci` | CI changes | (usually excluded) |
| `build` | Build system | (usually excluded) |
| `revert` | Revert commit | Removed |
### 3. Semantic Versioning
@@ -143,23 +150,24 @@ echo "npx --no -- commitlint --edit \$1" > .husky/commit-msg
// .versionrc.js
module.exports = {
types: [
{ type: 'feat', section: 'Features' },
{ type: 'fix', section: 'Bug Fixes' },
{ type: 'perf', section: 'Performance Improvements' },
{ type: 'revert', section: 'Reverts' },
{ type: 'docs', section: 'Documentation', hidden: true },
{ type: 'style', section: 'Styles', hidden: true },
{ type: 'chore', section: 'Miscellaneous', hidden: true },
{ type: 'refactor', section: 'Code Refactoring', hidden: true },
{ type: 'test', section: 'Tests', hidden: true },
{ type: 'build', section: 'Build System', hidden: true },
{ type: 'ci', section: 'CI/CD', hidden: true },
{ type: "feat", section: "Features" },
{ type: "fix", section: "Bug Fixes" },
{ type: "perf", section: "Performance Improvements" },
{ type: "revert", section: "Reverts" },
{ type: "docs", section: "Documentation", hidden: true },
{ type: "style", section: "Styles", hidden: true },
{ type: "chore", section: "Miscellaneous", hidden: true },
{ type: "refactor", section: "Code Refactoring", hidden: true },
{ type: "test", section: "Tests", hidden: true },
{ type: "build", section: "Build System", hidden: true },
{ type: "ci", section: "CI/CD", hidden: true },
],
commitUrlFormat: '{{host}}/{{owner}}/{{repository}}/commit/{{hash}}',
compareUrlFormat: '{{host}}/{{owner}}/{{repository}}/compare/{{previousTag}}...{{currentTag}}',
issueUrlFormat: '{{host}}/{{owner}}/{{repository}}/issues/{{id}}',
userUrlFormat: '{{host}}/{{user}}',
releaseCommitMessageFormat: 'chore(release): {{currentTag}}',
commitUrlFormat: "{{host}}/{{owner}}/{{repository}}/commit/{{hash}}",
compareUrlFormat:
"{{host}}/{{owner}}/{{repository}}/compare/{{previousTag}}...{{currentTag}}",
issueUrlFormat: "{{host}}/{{owner}}/{{repository}}/issues/{{id}}",
userUrlFormat: "{{host}}/{{user}}",
releaseCommitMessageFormat: "chore(release): {{currentTag}}",
scripts: {
prebump: 'echo "Running prebump"',
postbump: 'echo "Running postbump"',
@@ -188,36 +196,37 @@ module.exports = {
// release.config.js
module.exports = {
branches: [
'main',
{ name: 'beta', prerelease: true },
{ name: 'alpha', prerelease: true },
"main",
{ name: "beta", prerelease: true },
{ name: "alpha", prerelease: true },
],
plugins: [
'@semantic-release/commit-analyzer',
'@semantic-release/release-notes-generator',
"@semantic-release/commit-analyzer",
"@semantic-release/release-notes-generator",
[
'@semantic-release/changelog',
"@semantic-release/changelog",
{
changelogFile: 'CHANGELOG.md',
changelogFile: "CHANGELOG.md",
},
],
[
'@semantic-release/npm',
"@semantic-release/npm",
{
npmPublish: true,
},
],
[
'@semantic-release/github',
"@semantic-release/github",
{
assets: ['dist/**/*.js', 'dist/**/*.css'],
assets: ["dist/**/*.js", "dist/**/*.css"],
},
],
[
'@semantic-release/git',
"@semantic-release/git",
{
assets: ['CHANGELOG.md', 'package.json'],
message: 'chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}',
assets: ["CHANGELOG.md", "package.json"],
message:
"chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}",
},
],
],
@@ -236,9 +245,9 @@ on:
workflow_dispatch:
inputs:
release_type:
description: 'Release type'
description: "Release type"
required: true
default: 'patch'
default: "patch"
type: choice
options:
- patch
@@ -260,8 +269,8 @@ jobs:
- uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
node-version: "20"
cache: "npm"
- run: npm ci
@@ -287,7 +296,7 @@ jobs:
- uses: actions/setup-node@v4
with:
node-version: '20'
node-version: "20"
- run: npm ci
@@ -434,29 +443,39 @@ cz check --rev-range HEAD~5..HEAD
## What's Changed
### 🚀 Features
{{ range .Features }}
- {{ .Title }} by @{{ .Author }} in #{{ .PR }}
{{ end }}
{{ end }}
### 🐛 Bug Fixes
{{ range .Fixes }}
- {{ .Title }} by @{{ .Author }} in #{{ .PR }}
{{ end }}
{{ end }}
### 📚 Documentation
{{ range .Docs }}
- {{ .Title }} by @{{ .Author }} in #{{ .PR }}
{{ end }}
{{ end }}
### 🔧 Maintenance
{{ range .Chores }}
- {{ .Title }} by @{{ .Author }} in #{{ .PR }}
{{ end }}
{{ end }}
## New Contributors
{{ range .NewContributors }}
- @{{ .Username }} made their first contribution in #{{ .PR }}
{{ end }}
{{ end }}
**Full Changelog**: https://github.com/owner/repo/compare/v{{ .Previous }}...v{{ .Current }}
```
@@ -467,33 +486,40 @@ cz check --rev-range HEAD~5..HEAD
# Release v2.1.0 - January 15, 2024
## Summary
This release introduces dark mode support and improves checkout performance
by 40%. It also includes important security updates.
## Highlights
### 🌙 Dark Mode
Users can now switch to dark mode from settings. The preference is
automatically saved and synced across devices.
### ⚡ Performance
- Checkout flow is 40% faster
- Reduced bundle size by 15%
## Breaking Changes
None in this release.
## Upgrade Guide
No special steps required. Standard deployment process applies.
## Known Issues
- Dark mode may flicker on initial load (fix scheduled for v2.1.1)
## Dependencies Updated
| Package | From | To | Reason |
|---------|------|-----|--------|
| react | 18.2.0 | 18.3.0 | Performance improvements |
| lodash | 4.17.20 | 4.17.21 | Security patch |
| Package | From | To | Reason |
| ------- | ------- | ------- | ------------------------ |
| react | 18.2.0 | 18.3.0 | Performance improvements |
| lodash | 4.17.20 | 4.17.21 | Security patch |
```
## Commit Message Examples
@@ -530,6 +556,7 @@ Reviewed-by: @alice
## Best Practices
### Do's
- **Follow Conventional Commits** - Enables automation
- **Write clear messages** - Future you will thank you
- **Reference issues** - Link commits to tickets
@@ -537,6 +564,7 @@ Reviewed-by: @alice
- **Automate releases** - Reduce manual errors
### Don'ts
- **Don't mix changes** - One logical change per commit
- **Don't skip validation** - Use commitlint
- **Don't manual edit** - Generated changelogs only

View File

@@ -37,11 +37,11 @@ components:
### 2. Design Approaches
| Approach | Description | Best For |
|----------|-------------|----------|
| **Design-First** | Write spec before code | New APIs, contracts |
| **Code-First** | Generate spec from code | Existing APIs |
| **Hybrid** | Annotate code, generate spec | Evolving APIs |
| Approach | Description | Best For |
| ---------------- | ---------------------------- | ------------------- |
| **Design-First** | Write spec before code | New APIs, contracts |
| **Code-First** | Generate spec from code | Existing APIs |
| **Hybrid** | Annotate code, generate spec | Evolving APIs |
## Templates
@@ -94,13 +94,13 @@ paths:
tags:
- Users
parameters:
- $ref: '#/components/parameters/PageParam'
- $ref: '#/components/parameters/LimitParam'
- $ref: "#/components/parameters/PageParam"
- $ref: "#/components/parameters/LimitParam"
- name: status
in: query
description: Filter by user status
schema:
$ref: '#/components/schemas/UserStatus'
$ref: "#/components/schemas/UserStatus"
- name: search
in: query
description: Search by name or email
@@ -109,21 +109,21 @@ paths:
minLength: 2
maxLength: 100
responses:
'200':
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/UserListResponse'
$ref: "#/components/schemas/UserListResponse"
examples:
default:
$ref: '#/components/examples/UserListExample'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/RateLimited'
$ref: "#/components/examples/UserListExample"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"429":
$ref: "#/components/responses/RateLimited"
security:
- bearerAuth: []
@@ -138,7 +138,7 @@ paths:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUserRequest'
$ref: "#/components/schemas/CreateUserRequest"
examples:
standard:
summary: Standard user
@@ -153,32 +153,32 @@ paths:
name: Admin User
role: admin
responses:
'201':
"201":
description: User created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/User'
$ref: "#/components/schemas/User"
headers:
Location:
description: URL of created user
schema:
type: string
format: uri
'400':
$ref: '#/components/responses/BadRequest'
'409':
"400":
$ref: "#/components/responses/BadRequest"
"409":
description: Email already exists
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
$ref: "#/components/schemas/Error"
security:
- bearerAuth: []
/users/{userId}:
parameters:
- $ref: '#/components/parameters/UserIdParam'
- $ref: "#/components/parameters/UserIdParam"
get:
operationId: getUser
@@ -186,14 +186,14 @@ paths:
tags:
- Users
responses:
'200':
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'404':
$ref: '#/components/responses/NotFound'
$ref: "#/components/schemas/User"
"404":
$ref: "#/components/responses/NotFound"
security:
- bearerAuth: []
@@ -207,18 +207,18 @@ paths:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateUserRequest'
$ref: "#/components/schemas/UpdateUserRequest"
responses:
'200':
"200":
description: User updated
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
$ref: "#/components/schemas/User"
"400":
$ref: "#/components/responses/BadRequest"
"404":
$ref: "#/components/responses/NotFound"
security:
- bearerAuth: []
@@ -229,10 +229,10 @@ paths:
- Users
- Admin
responses:
'204':
"204":
description: User deleted
'404':
$ref: '#/components/responses/NotFound'
"404":
$ref: "#/components/responses/NotFound"
security:
- bearerAuth: []
- apiKey: []
@@ -263,7 +263,7 @@ components:
maxLength: 100
description: User display name
status:
$ref: '#/components/schemas/UserStatus'
$ref: "#/components/schemas/UserStatus"
role:
type: string
enum: [user, moderator, admin]
@@ -320,7 +320,7 @@ components:
minLength: 1
maxLength: 100
status:
$ref: '#/components/schemas/UserStatus'
$ref: "#/components/schemas/UserStatus"
role:
type: string
enum: [user, moderator, admin]
@@ -337,9 +337,9 @@ components:
data:
type: array
items:
$ref: '#/components/schemas/User'
$ref: "#/components/schemas/User"
pagination:
$ref: '#/components/schemas/Pagination'
$ref: "#/components/schemas/Pagination"
Pagination:
type: object
@@ -427,7 +427,7 @@ components:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
$ref: "#/components/schemas/Error"
example:
code: VALIDATION_ERROR
message: Invalid request parameters
@@ -440,7 +440,7 @@ components:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
$ref: "#/components/schemas/Error"
example:
code: UNAUTHORIZED
message: Authentication required
@@ -450,7 +450,7 @@ components:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
$ref: "#/components/schemas/Error"
example:
code: NOT_FOUND
message: User not found
@@ -460,7 +460,7 @@ components:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
$ref: "#/components/schemas/Error"
headers:
Retry-After:
description: Seconds until rate limit resets
@@ -826,7 +826,7 @@ export class UsersController extends Controller {
@Query() page: number = 1,
@Query() limit: number = 20,
@Query() status?: UserStatus,
@Query() search?: string
@Query() search?: string,
): Promise<UserListResponse> {
// Implementation
throw new Error("Not implemented");
@@ -840,9 +840,7 @@ export class UsersController extends Controller {
@SuccessResponse(201, "Created")
@Response<ErrorResponse>(400, "Invalid request")
@Response<ErrorResponse>(409, "Email already exists")
public async createUser(
@Body() body: CreateUserRequest
): Promise<User> {
public async createUser(@Body() body: CreateUserRequest): Promise<User> {
this.setStatus(201);
throw new Error("Not implemented");
}
@@ -854,9 +852,7 @@ export class UsersController extends Controller {
@Get("{userId}")
@Security("bearerAuth")
@Response<ErrorResponse>(404, "User not found")
public async getUser(
@Path() userId: string
): Promise<User> {
public async getUser(@Path() userId: string): Promise<User> {
throw new Error("Not implemented");
}
@@ -870,7 +866,7 @@ export class UsersController extends Controller {
@Response<ErrorResponse>(404, "User not found")
public async updateUser(
@Path() userId: string,
@Body() body: UpdateUserRequest
@Body() body: UpdateUserRequest,
): Promise<User> {
throw new Error("Not implemented");
}
@@ -884,9 +880,7 @@ export class UsersController extends Controller {
@Security("bearerAuth")
@SuccessResponse(204, "Deleted")
@Response<ErrorResponse>(404, "User not found")
public async deleteUser(
@Path() userId: string
): Promise<void> {
public async deleteUser(@Path() userId: string): Promise<void> {
this.setStatus(204);
}
}
@@ -1007,6 +1001,7 @@ openapi-generator-cli generate \
## Best Practices
### Do's
- **Use $ref** - Reuse schemas, parameters, responses
- **Add examples** - Real-world values help consumers
- **Document errors** - All possible error codes
@@ -1014,6 +1009,7 @@ openapi-generator-cli generate \
- **Use semantic versioning** - For spec changes
### Don'ts
- **Don't use generic descriptions** - Be specific
- **Don't skip security** - Define all schemes
- **Don't forget nullable** - Be explicit about null