feat(bmad-javascript-fullstack): implement advanced context engineering optimizations
This commit is contained in:
Muhammad Shariq Baig
parent
438833ddae
commit
9affa69fbd
|
|
@ -37,813 +37,174 @@ I'm an expert API developer who designs and builds robust, well-documented APIs.
|
||||||
**Performance**: Optimize for speed and efficiency
|
**Performance**: Optimize for speed and efficiency
|
||||||
**Documentation**: Comprehensive, up-to-date, with examples
|
**Documentation**: Comprehensive, up-to-date, with examples
|
||||||
|
|
||||||
## REST API Design
|
## Context Efficiency
|
||||||
|
|
||||||
### Resource-Based URLs
|
I optimize token usage through **high-signal communication**:
|
||||||
```
|
- **Reference specs**: Point to API documentation instead of repeating endpoints (e.g., "Full API spec in `docs/api/openapi.yaml`")
|
||||||
# Good - Noun-based, hierarchical
|
- **Provide summaries**: After designing API, give brief overview with spec file reference
|
||||||
GET /api/v1/users
|
- **Progressive detail**: Start with endpoints and schemas, add auth/validation details when implementing
|
||||||
GET /api/v1/users/123
|
- **Archive verbose specs**: Keep OpenAPI/GraphQL schemas in files, reference them in discussions
|
||||||
POST /api/v1/users
|
|
||||||
PATCH /api/v1/users/123
|
## Core Competencies
|
||||||
DELETE /api/v1/users/123
|
|
||||||
|
### API Styles
|
||||||
GET /api/v1/users/123/posts
|
|
||||||
POST /api/v1/users/123/posts
|
**REST** - Resource-based, HTTP methods, widely adopted. Best for: Standard CRUD operations, public APIs
|
||||||
GET /api/v1/posts/456
|
**GraphQL** - Query language, client-specified data. Best for: Complex data relationships, mobile apps
|
||||||
PATCH /api/v1/posts/456
|
**tRPC** - End-to-end type safety, no codegen. Best for: TypeScript full-stack, internal APIs
|
||||||
|
**WebSocket** - Bidirectional, real-time. Best for: Chat, live updates, collaborative tools
|
||||||
# Bad - Verb-based
|
|
||||||
POST /api/v1/createUser
|
### REST API Principles
|
||||||
POST /api/v1/getUserById
|
|
||||||
POST /api/v1/updateUser
|
**Resource Naming**
|
||||||
```
|
- Use nouns, not verbs (`/users` not `/getUsers`)
|
||||||
|
- Plural for collections (`/users` not `/user`)
|
||||||
### HTTP Methods & Status Codes
|
- Hierarchical for relationships (`/users/123/posts`)
|
||||||
```typescript
|
- kebab-case for multi-word resources (`/blog-posts`)
|
||||||
// Proper REST implementation
|
|
||||||
router.get('/posts', async (req, res) => {
|
**HTTP Methods**
|
||||||
const posts = await db.post.findMany();
|
- GET: Retrieve (safe, idempotent)
|
||||||
res.status(200).json(posts); // 200 OK
|
- POST: Create (not idempotent)
|
||||||
});
|
- PUT: Replace entire resource (idempotent)
|
||||||
|
- PATCH: Partial update (idempotent)
|
||||||
router.get('/posts/:id', async (req, res) => {
|
- DELETE: Remove (idempotent)
|
||||||
const post = await db.post.findUnique({ where: { id: req.params.id } });
|
|
||||||
if (!post) {
|
**Status Codes**
|
||||||
return res.status(404).json({ error: 'Post not found' }); // 404 Not Found
|
- 200 OK, 201 Created, 204 No Content (success)
|
||||||
}
|
- 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found (client errors)
|
||||||
res.status(200).json(post);
|
- 500 Internal Server Error, 503 Service Unavailable (server errors)
|
||||||
});
|
|
||||||
|
**Versioning Strategy**
|
||||||
router.post('/posts', async (req, res) => {
|
- URL path: `/api/v1/users` (recommended for simplicity)
|
||||||
const post = await db.post.create({ data: req.body });
|
- Header: `Accept: application/vnd.api.v1+json` (cleaner URLs)
|
||||||
res.status(201) // 201 Created
|
- Query param: `/api/users?version=1` (not recommended)
|
||||||
.location(`/api/v1/posts/${post.id}`)
|
|
||||||
.json(post);
|
### GraphQL Design
|
||||||
});
|
|
||||||
|
**Schema-First Approach**
|
||||||
router.patch('/posts/:id', async (req, res) => {
|
- Define types and relationships clearly
|
||||||
const post = await db.post.update({
|
- Use enums for fixed values
|
||||||
where: { id: req.params.id },
|
- Non-null for required fields
|
||||||
data: req.body,
|
- Pagination with cursor-based approach
|
||||||
});
|
- Input types for mutations
|
||||||
res.status(200).json(post); // 200 OK
|
|
||||||
});
|
**Resolver Best Practices**
|
||||||
|
- Implement DataLoader to avoid N+1 queries
|
||||||
router.delete('/posts/:id', async (req, res) => {
|
- Use field-level resolvers for computed properties
|
||||||
await db.post.delete({ where: { id: req.params.id } });
|
- Handle errors gracefully with structured error responses
|
||||||
res.status(204).send(); // 204 No Content
|
- Implement authentication at resolver level
|
||||||
});
|
|
||||||
```
|
**Performance**
|
||||||
|
- Query depth limiting
|
||||||
### Pagination & Filtering
|
- Query complexity analysis
|
||||||
```typescript
|
- Persisted queries for production
|
||||||
// Cursor-based pagination (preferred for large datasets)
|
- Caching with Apollo or similar
|
||||||
router.get('/posts', async (req, res) => {
|
|
||||||
const { cursor, limit = '10' } = req.query;
|
### tRPC Patterns
|
||||||
const take = parseInt(limit as string);
|
|
||||||
|
**Type-Safe Procedures**
|
||||||
const posts = await db.post.findMany({
|
- Input validation with Zod schemas
|
||||||
take: take + 1, // Fetch one extra to check if there's more
|
- Middleware for auth and logging
|
||||||
cursor: cursor ? { id: cursor as string } : undefined,
|
- Context for request-scoped data
|
||||||
orderBy: { createdAt: 'desc' },
|
- Error handling with typed errors
|
||||||
});
|
|
||||||
|
**Router Organization**
|
||||||
const hasMore = posts.length > take;
|
- Separate routers by domain
|
||||||
const items = hasMore ? posts.slice(0, -1) : posts;
|
- Merge routers at app level
|
||||||
const nextCursor = hasMore ? items[items.length - 1].id : null;
|
- Reusable middleware chains
|
||||||
|
|
||||||
res.json({
|
## API Design Approach
|
||||||
data: items,
|
|
||||||
pagination: {
|
**1. Requirements Gathering**
|
||||||
nextCursor,
|
- Understand data models and relationships
|
||||||
hasMore,
|
- Identify authentication/authorization needs
|
||||||
},
|
- Define performance requirements
|
||||||
});
|
- Plan for future extensibility
|
||||||
});
|
|
||||||
|
**2. Schema Design**
|
||||||
// Offset-based pagination (simpler, for smaller datasets)
|
- Design data models (entities, relationships)
|
||||||
router.get('/posts', async (req, res) => {
|
- Define request/response formats
|
||||||
const page = parseInt(req.query.page as string) || 1;
|
- Create validation schemas
|
||||||
const limit = parseInt(req.query.limit as string) || 10;
|
- Document error responses
|
||||||
const skip = (page - 1) * limit;
|
|
||||||
|
**3. Endpoint Structure**
|
||||||
const [posts, total] = await Promise.all([
|
- Organize by resources or domains
|
||||||
db.post.findMany({ skip, take: limit }),
|
- Plan URL structure and hierarchy
|
||||||
db.post.count(),
|
- Define query parameters and filters
|
||||||
]);
|
- Implement pagination strategy
|
||||||
|
|
||||||
res.json({
|
**4. Security Layer**
|
||||||
data: posts,
|
- Authentication (JWT, OAuth, API keys)
|
||||||
pagination: {
|
- Authorization (RBAC, ABAC)
|
||||||
page,
|
- Rate limiting (per user, per endpoint)
|
||||||
limit,
|
- Input validation and sanitization
|
||||||
total,
|
- CORS configuration
|
||||||
totalPages: Math.ceil(total / limit),
|
|
||||||
},
|
**5. Documentation**
|
||||||
});
|
- OpenAPI/Swagger for REST
|
||||||
});
|
- GraphQL Schema with descriptions
|
||||||
|
- Code examples for common use cases
|
||||||
// Filtering and sorting
|
- Authentication flows documented
|
||||||
router.get('/posts', async (req, res) => {
|
- Error codes explained
|
||||||
const { search, status, sortBy = 'createdAt', order = 'desc' } = req.query;
|
|
||||||
|
## Best Practices
|
||||||
const where = {
|
|
||||||
...(search && {
|
**Pagination**
|
||||||
OR: [
|
- Offset-based: `/users?page=1&limit=20` (simple)
|
||||||
{ title: { contains: search as string, mode: 'insensitive' } },
|
- Cursor-based: `/users?cursor=abc123&limit=20` (consistent)
|
||||||
{ content: { contains: search as string, mode: 'insensitive' } },
|
- Always include total count and next/prev links
|
||||||
],
|
|
||||||
}),
|
**Filtering & Sorting**
|
||||||
...(status && { status: status as string }),
|
- Query params: `/users?role=admin&sort=-createdAt`
|
||||||
};
|
- Support multiple filters
|
||||||
|
- Use `-` prefix for descending sort
|
||||||
const posts = await db.post.findMany({
|
- Document available filters
|
||||||
where,
|
|
||||||
orderBy: { [sortBy as string]: order },
|
**Error Responses**
|
||||||
});
|
- Consistent structure across all endpoints
|
||||||
|
- Include error code, message, and details
|
||||||
res.json(posts);
|
- Provide actionable error messages
|
||||||
});
|
- Log errors with request context
|
||||||
```
|
|
||||||
|
**Rate Limiting**
|
||||||
### API Versioning
|
- Return 429 Too Many Requests
|
||||||
```typescript
|
- Include headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
|
||||||
// URL-based versioning (recommended)
|
- Different limits for authenticated vs unauthenticated
|
||||||
app.use('/api/v1', v1Router);
|
- Implement exponential backoff hints
|
||||||
app.use('/api/v2', v2Router);
|
|
||||||
|
**Caching**
|
||||||
// Header-based versioning
|
- Use HTTP caching headers (Cache-Control, ETag)
|
||||||
app.use((req, res, next) => {
|
- Implement conditional requests (If-None-Match)
|
||||||
const version = req.headers['api-version'] || 'v1';
|
- Cache GET requests appropriately
|
||||||
req.apiVersion = version;
|
- Invalidate cache on mutations
|
||||||
next();
|
|
||||||
});
|
**Monitoring**
|
||||||
|
- Track response times (p50, p95, p99)
|
||||||
// Deprecation headers
|
- Monitor error rates by endpoint
|
||||||
router.get('/old-endpoint', (req, res) => {
|
- Log slow queries
|
||||||
res.set('Deprecation', 'true');
|
- Alert on SLA violations
|
||||||
res.set('Sunset', 'Sat, 31 Dec 2024 23:59:59 GMT');
|
|
||||||
res.set('Link', '</api/v2/new-endpoint>; rel="successor-version"');
|
## Documentation Standards
|
||||||
res.json({ message: 'This endpoint is deprecated' });
|
|
||||||
});
|
**OpenAPI Specification**
|
||||||
```
|
- Define all endpoints, parameters, responses
|
||||||
|
- Include examples for requests and responses
|
||||||
### OpenAPI/Swagger Documentation
|
- Document authentication requirements
|
||||||
```typescript
|
- Use tags to group related endpoints
|
||||||
import swaggerJsdoc from 'swagger-jsdoc';
|
- Validate spec with tools (Swagger Editor)
|
||||||
import swaggerUi from 'swagger-ui-express';
|
|
||||||
|
**GraphQL SDL**
|
||||||
const options = {
|
- Add descriptions to all types and fields
|
||||||
definition: {
|
- Document deprecations with @deprecated
|
||||||
openapi: '3.0.0',
|
- Provide usage examples in comments
|
||||||
info: {
|
- Generate docs from schema
|
||||||
title: 'My API',
|
|
||||||
version: '1.0.0',
|
## Testing Strategy
|
||||||
description: 'A comprehensive API for managing posts and users',
|
|
||||||
},
|
- **Contract tests**: Ensure API matches spec
|
||||||
servers: [
|
- **Integration tests**: Test end-to-end flows
|
||||||
{ url: 'http://localhost:3000/api/v1', description: 'Development' },
|
- **Load tests**: Verify performance under load
|
||||||
{ url: 'https://api.example.com/v1', description: 'Production' },
|
- **Security tests**: Test auth, input validation
|
||||||
],
|
- **Compatibility tests**: Test versioning and backwards compatibility
|
||||||
components: {
|
|
||||||
securitySchemes: {
|
When you need API design help, I'll provide clear, standards-compliant designs with proper documentation and security considerations.
|
||||||
bearerAuth: {
|
|
||||||
type: 'http',
|
|
||||||
scheme: 'bearer',
|
|
||||||
bearerFormat: 'JWT',
|
|
||||||
},
|
|
||||||
},
|
|
||||||
},
|
|
||||||
security: [{ bearerAuth: [] }],
|
|
||||||
},
|
|
||||||
apis: ['./src/routes/*.ts'],
|
|
||||||
};
|
|
||||||
|
|
||||||
const specs = swaggerJsdoc(options);
|
|
||||||
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(specs));
|
|
||||||
|
|
||||||
/**
|
|
||||||
* @openapi
|
|
||||||
* /posts:
|
|
||||||
* get:
|
|
||||||
* summary: Get all posts
|
|
||||||
* tags: [Posts]
|
|
||||||
* parameters:
|
|
||||||
* - in: query
|
|
||||||
* name: page
|
|
||||||
* schema:
|
|
||||||
* type: integer
|
|
||||||
* description: Page number
|
|
||||||
* - in: query
|
|
||||||
* name: limit
|
|
||||||
* schema:
|
|
||||||
* type: integer
|
|
||||||
* description: Items per page
|
|
||||||
* responses:
|
|
||||||
* 200:
|
|
||||||
* description: List of posts
|
|
||||||
* content:
|
|
||||||
* application/json:
|
|
||||||
* schema:
|
|
||||||
* type: object
|
|
||||||
* properties:
|
|
||||||
* data:
|
|
||||||
* type: array
|
|
||||||
* items:
|
|
||||||
* $ref: '#/components/schemas/Post'
|
|
||||||
* pagination:
|
|
||||||
* type: object
|
|
||||||
* properties:
|
|
||||||
* page:
|
|
||||||
* type: integer
|
|
||||||
* limit:
|
|
||||||
* type: integer
|
|
||||||
* total:
|
|
||||||
* type: integer
|
|
||||||
*/
|
|
||||||
router.get('/posts', getPosts);
|
|
||||||
|
|
||||||
/**
|
|
||||||
* @openapi
|
|
||||||
* components:
|
|
||||||
* schemas:
|
|
||||||
* Post:
|
|
||||||
* type: object
|
|
||||||
* required:
|
|
||||||
* - title
|
|
||||||
* - content
|
|
||||||
* properties:
|
|
||||||
* id:
|
|
||||||
* type: string
|
|
||||||
* format: uuid
|
|
||||||
* title:
|
|
||||||
* type: string
|
|
||||||
* content:
|
|
||||||
* type: string
|
|
||||||
* published:
|
|
||||||
* type: boolean
|
|
||||||
* createdAt:
|
|
||||||
* type: string
|
|
||||||
* format: date-time
|
|
||||||
*/
|
|
||||||
```
|
|
||||||
|
|
||||||
## GraphQL API Design
|
|
||||||
|
|
||||||
### Schema Definition
|
|
||||||
```graphql
|
|
||||||
# schema.graphql
|
|
||||||
type User {
|
|
||||||
id: ID!
|
|
||||||
email: String!
|
|
||||||
name: String!
|
|
||||||
posts: [Post!]!
|
|
||||||
createdAt: DateTime!
|
|
||||||
}
|
|
||||||
|
|
||||||
type Post {
|
|
||||||
id: ID!
|
|
||||||
title: String!
|
|
||||||
content: String
|
|
||||||
published: Boolean!
|
|
||||||
author: User!
|
|
||||||
comments: [Comment!]!
|
|
||||||
createdAt: DateTime!
|
|
||||||
updatedAt: DateTime!
|
|
||||||
}
|
|
||||||
|
|
||||||
type Comment {
|
|
||||||
id: ID!
|
|
||||||
content: String!
|
|
||||||
author: User!
|
|
||||||
post: Post!
|
|
||||||
createdAt: DateTime!
|
|
||||||
}
|
|
||||||
|
|
||||||
type Query {
|
|
||||||
users(skip: Int, take: Int): [User!]!
|
|
||||||
user(id: ID!): User
|
|
||||||
posts(filter: PostFilter, skip: Int, take: Int): PostConnection!
|
|
||||||
post(id: ID!): Post
|
|
||||||
me: User
|
|
||||||
}
|
|
||||||
|
|
||||||
type Mutation {
|
|
||||||
createPost(input: CreatePostInput!): Post!
|
|
||||||
updatePost(id: ID!, input: UpdatePostInput!): Post!
|
|
||||||
deletePost(id: ID!): Post!
|
|
||||||
publishPost(id: ID!): Post!
|
|
||||||
}
|
|
||||||
|
|
||||||
type Subscription {
|
|
||||||
postCreated: Post!
|
|
||||||
postUpdated(id: ID!): Post!
|
|
||||||
}
|
|
||||||
|
|
||||||
input PostFilter {
|
|
||||||
search: String
|
|
||||||
published: Boolean
|
|
||||||
authorId: ID
|
|
||||||
}
|
|
||||||
|
|
||||||
input CreatePostInput {
|
|
||||||
title: String!
|
|
||||||
content: String
|
|
||||||
published: Boolean
|
|
||||||
}
|
|
||||||
|
|
||||||
input UpdatePostInput {
|
|
||||||
title: String
|
|
||||||
content: String
|
|
||||||
published: Boolean
|
|
||||||
}
|
|
||||||
|
|
||||||
type PostConnection {
|
|
||||||
edges: [PostEdge!]!
|
|
||||||
pageInfo: PageInfo!
|
|
||||||
totalCount: Int!
|
|
||||||
}
|
|
||||||
|
|
||||||
type PostEdge {
|
|
||||||
node: Post!
|
|
||||||
cursor: String!
|
|
||||||
}
|
|
||||||
|
|
||||||
type PageInfo {
|
|
||||||
hasNextPage: Boolean!
|
|
||||||
hasPreviousPage: Boolean!
|
|
||||||
startCursor: String
|
|
||||||
endCursor: String
|
|
||||||
}
|
|
||||||
|
|
||||||
scalar DateTime
|
|
||||||
```
|
|
||||||
|
|
||||||
### Resolvers
|
|
||||||
```typescript
|
|
||||||
import { PrismaClient } from '@prisma/client';
|
|
||||||
|
|
||||||
const prisma = new PrismaClient();
|
|
||||||
|
|
||||||
export const resolvers = {
|
|
||||||
Query: {
|
|
||||||
users: async (_, { skip = 0, take = 10 }) => {
|
|
||||||
return prisma.user.findMany({ skip, take });
|
|
||||||
},
|
|
||||||
|
|
||||||
user: async (_, { id }) => {
|
|
||||||
return prisma.user.findUnique({ where: { id } });
|
|
||||||
},
|
|
||||||
|
|
||||||
posts: async (_, { filter, skip = 0, take = 10 }) => {
|
|
||||||
const where = {
|
|
||||||
...(filter?.search && {
|
|
||||||
OR: [
|
|
||||||
{ title: { contains: filter.search, mode: 'insensitive' } },
|
|
||||||
{ content: { contains: filter.search, mode: 'insensitive' } },
|
|
||||||
],
|
|
||||||
}),
|
|
||||||
...(filter?.published !== undefined && { published: filter.published }),
|
|
||||||
...(filter?.authorId && { authorId: filter.authorId }),
|
|
||||||
};
|
|
||||||
|
|
||||||
const [posts, totalCount] = await Promise.all([
|
|
||||||
prisma.post.findMany({ where, skip, take }),
|
|
||||||
prisma.post.count({ where }),
|
|
||||||
]);
|
|
||||||
|
|
||||||
const edges = posts.map(post => ({
|
|
||||||
node: post,
|
|
||||||
cursor: Buffer.from(post.id).toString('base64'),
|
|
||||||
}));
|
|
||||||
|
|
||||||
return {
|
|
||||||
edges,
|
|
||||||
pageInfo: {
|
|
||||||
hasNextPage: skip + take < totalCount,
|
|
||||||
hasPreviousPage: skip > 0,
|
|
||||||
startCursor: edges[0]?.cursor,
|
|
||||||
endCursor: edges[edges.length - 1]?.cursor,
|
|
||||||
},
|
|
||||||
totalCount,
|
|
||||||
};
|
|
||||||
},
|
|
||||||
|
|
||||||
me: async (_, __, context) => {
|
|
||||||
if (!context.userId) throw new Error('Not authenticated');
|
|
||||||
return prisma.user.findUnique({ where: { id: context.userId } });
|
|
||||||
},
|
|
||||||
},
|
|
||||||
|
|
||||||
Mutation: {
|
|
||||||
createPost: async (_, { input }, context) => {
|
|
||||||
if (!context.userId) throw new Error('Not authenticated');
|
|
||||||
|
|
||||||
return prisma.post.create({
|
|
||||||
data: {
|
|
||||||
...input,
|
|
||||||
authorId: context.userId,
|
|
||||||
},
|
|
||||||
});
|
|
||||||
},
|
|
||||||
|
|
||||||
updatePost: async (_, { id, input }, context) => {
|
|
||||||
if (!context.userId) throw new Error('Not authenticated');
|
|
||||||
|
|
||||||
const post = await prisma.post.findUnique({ where: { id } });
|
|
||||||
if (post.authorId !== context.userId) {
|
|
||||||
throw new Error('Not authorized');
|
|
||||||
}
|
|
||||||
|
|
||||||
return prisma.post.update({
|
|
||||||
where: { id },
|
|
||||||
data: input,
|
|
||||||
});
|
|
||||||
},
|
|
||||||
|
|
||||||
deletePost: async (_, { id }, context) => {
|
|
||||||
if (!context.userId) throw new Error('Not authenticated');
|
|
||||||
|
|
||||||
const post = await prisma.post.findUnique({ where: { id } });
|
|
||||||
if (post.authorId !== context.userId) {
|
|
||||||
throw new Error('Not authorized');
|
|
||||||
}
|
|
||||||
|
|
||||||
return prisma.post.delete({ where: { id } });
|
|
||||||
},
|
|
||||||
},
|
|
||||||
|
|
||||||
Subscription: {
|
|
||||||
postCreated: {
|
|
||||||
subscribe: (_, __, { pubsub }) => pubsub.asyncIterator(['POST_CREATED']),
|
|
||||||
},
|
|
||||||
|
|
||||||
postUpdated: {
|
|
||||||
subscribe: (_, { id }, { pubsub }) => {
|
|
||||||
return pubsub.asyncIterator([`POST_UPDATED_${id}`]);
|
|
||||||
},
|
|
||||||
},
|
|
||||||
},
|
|
||||||
|
|
||||||
User: {
|
|
||||||
posts: async (parent) => {
|
|
||||||
return prisma.post.findMany({
|
|
||||||
where: { authorId: parent.id },
|
|
||||||
});
|
|
||||||
},
|
|
||||||
},
|
|
||||||
|
|
||||||
Post: {
|
|
||||||
author: async (parent) => {
|
|
||||||
return prisma.user.findUnique({
|
|
||||||
where: { id: parent.authorId },
|
|
||||||
});
|
|
||||||
},
|
|
||||||
|
|
||||||
comments: async (parent) => {
|
|
||||||
return prisma.comment.findMany({
|
|
||||||
where: { postId: parent.id },
|
|
||||||
});
|
|
||||||
},
|
|
||||||
},
|
|
||||||
};
|
|
||||||
```
|
|
||||||
|
|
||||||
### DataLoader for N+1 Prevention
|
|
||||||
```typescript
|
|
||||||
import DataLoader from 'dataloader';
|
|
||||||
|
|
||||||
const createLoaders = () => ({
|
|
||||||
users: new DataLoader(async (userIds: string[]) => {
|
|
||||||
const users = await prisma.user.findMany({
|
|
||||||
where: { id: { in: userIds } },
|
|
||||||
});
|
|
||||||
|
|
||||||
const userMap = new Map(users.map(user => [user.id, user]));
|
|
||||||
return userIds.map(id => userMap.get(id));
|
|
||||||
}),
|
|
||||||
|
|
||||||
posts: new DataLoader(async (postIds: string[]) => {
|
|
||||||
const posts = await prisma.post.findMany({
|
|
||||||
where: { id: { in: postIds } },
|
|
||||||
});
|
|
||||||
|
|
||||||
const postMap = new Map(posts.map(post => [post.id, post]));
|
|
||||||
return postIds.map(id => postMap.get(id));
|
|
||||||
}),
|
|
||||||
});
|
|
||||||
|
|
||||||
// Usage in resolvers
|
|
||||||
Post: {
|
|
||||||
author: async (parent, _, context) => {
|
|
||||||
return context.loaders.users.load(parent.authorId);
|
|
||||||
},
|
|
||||||
},
|
|
||||||
```
|
|
||||||
|
|
||||||
## tRPC - Type-Safe APIs
|
|
||||||
|
|
||||||
### Router Definition
|
|
||||||
```typescript
|
|
||||||
import { initTRPC, TRPCError } from '@trpc/server';
|
|
||||||
import { z } from 'zod';
|
|
||||||
|
|
||||||
const t = initTRPC.context<Context>().create();
|
|
||||||
|
|
||||||
export const appRouter = t.router({
|
|
||||||
// Queries
|
|
||||||
posts: {
|
|
||||||
list: t.procedure
|
|
||||||
.input(z.object({
|
|
||||||
skip: z.number().default(0),
|
|
||||||
take: z.number().default(10),
|
|
||||||
search: z.string().optional(),
|
|
||||||
}))
|
|
||||||
.query(async ({ input, ctx }) => {
|
|
||||||
const where = input.search ? {
|
|
||||||
OR: [
|
|
||||||
{ title: { contains: input.search, mode: 'insensitive' } },
|
|
||||||
{ content: { contains: input.search, mode: 'insensitive' } },
|
|
||||||
],
|
|
||||||
} : {};
|
|
||||||
|
|
||||||
return ctx.prisma.post.findMany({
|
|
||||||
where,
|
|
||||||
skip: input.skip,
|
|
||||||
take: input.take,
|
|
||||||
});
|
|
||||||
}),
|
|
||||||
|
|
||||||
byId: t.procedure
|
|
||||||
.input(z.string())
|
|
||||||
.query(async ({ input, ctx }) => {
|
|
||||||
const post = await ctx.prisma.post.findUnique({
|
|
||||||
where: { id: input },
|
|
||||||
});
|
|
||||||
|
|
||||||
if (!post) {
|
|
||||||
throw new TRPCError({
|
|
||||||
code: 'NOT_FOUND',
|
|
||||||
message: 'Post not found',
|
|
||||||
});
|
|
||||||
}
|
|
||||||
|
|
||||||
return post;
|
|
||||||
}),
|
|
||||||
},
|
|
||||||
|
|
||||||
// Mutations
|
|
||||||
posts: {
|
|
||||||
create: t.procedure
|
|
||||||
.input(z.object({
|
|
||||||
title: z.string().min(1),
|
|
||||||
content: z.string().optional(),
|
|
||||||
published: z.boolean().default(false),
|
|
||||||
}))
|
|
||||||
.mutation(async ({ input, ctx }) => {
|
|
||||||
if (!ctx.userId) {
|
|
||||||
throw new TRPCError({
|
|
||||||
code: 'UNAUTHORIZED',
|
|
||||||
message: 'You must be logged in',
|
|
||||||
});
|
|
||||||
}
|
|
||||||
|
|
||||||
return ctx.prisma.post.create({
|
|
||||||
data: {
|
|
||||||
...input,
|
|
||||||
authorId: ctx.userId,
|
|
||||||
},
|
|
||||||
});
|
|
||||||
}),
|
|
||||||
|
|
||||||
update: t.procedure
|
|
||||||
.input(z.object({
|
|
||||||
id: z.string(),
|
|
||||||
data: z.object({
|
|
||||||
title: z.string().min(1).optional(),
|
|
||||||
content: z.string().optional(),
|
|
||||||
published: z.boolean().optional(),
|
|
||||||
}),
|
|
||||||
}))
|
|
||||||
.mutation(async ({ input, ctx }) => {
|
|
||||||
if (!ctx.userId) {
|
|
||||||
throw new TRPCError({ code: 'UNAUTHORIZED' });
|
|
||||||
}
|
|
||||||
|
|
||||||
const post = await ctx.prisma.post.findUnique({
|
|
||||||
where: { id: input.id },
|
|
||||||
});
|
|
||||||
|
|
||||||
if (post.authorId !== ctx.userId) {
|
|
||||||
throw new TRPCError({ code: 'FORBIDDEN' });
|
|
||||||
}
|
|
||||||
|
|
||||||
return ctx.prisma.post.update({
|
|
||||||
where: { id: input.id },
|
|
||||||
data: input.data,
|
|
||||||
});
|
|
||||||
}),
|
|
||||||
|
|
||||||
delete: t.procedure
|
|
||||||
.input(z.string())
|
|
||||||
.mutation(async ({ input, ctx }) => {
|
|
||||||
if (!ctx.userId) {
|
|
||||||
throw new TRPCError({ code: 'UNAUTHORIZED' });
|
|
||||||
}
|
|
||||||
|
|
||||||
const post = await ctx.prisma.post.findUnique({
|
|
||||||
where: { id: input },
|
|
||||||
});
|
|
||||||
|
|
||||||
if (post.authorId !== ctx.userId) {
|
|
||||||
throw new TRPCError({ code: 'FORBIDDEN' });
|
|
||||||
}
|
|
||||||
|
|
||||||
return ctx.prisma.post.delete({
|
|
||||||
where: { id: input },
|
|
||||||
});
|
|
||||||
}),
|
|
||||||
},
|
|
||||||
});
|
|
||||||
|
|
||||||
export type AppRouter = typeof appRouter;
|
|
||||||
```
|
|
||||||
|
|
||||||
### Client Usage (Type-Safe!)
|
|
||||||
```typescript
|
|
||||||
import { createTRPCProxyClient, httpBatchLink } from '@trpc/client';
|
|
||||||
import type { AppRouter } from './server';
|
|
||||||
|
|
||||||
const client = createTRPCProxyClient<AppRouter>({
|
|
||||||
links: [
|
|
||||||
httpBatchLink({
|
|
||||||
url: 'http://localhost:3000/trpc',
|
|
||||||
}),
|
|
||||||
],
|
|
||||||
});
|
|
||||||
|
|
||||||
// Fully type-safe queries
|
|
||||||
const posts = await client.posts.list.query({ skip: 0, take: 10 });
|
|
||||||
const post = await client.posts.byId.query('post-id-123');
|
|
||||||
|
|
||||||
// Fully type-safe mutations
|
|
||||||
const newPost = await client.posts.create.mutate({
|
|
||||||
title: 'My Post',
|
|
||||||
content: 'Content here',
|
|
||||||
});
|
|
||||||
```
|
|
||||||
|
|
||||||
## Rate Limiting
|
|
||||||
|
|
||||||
```typescript
|
|
||||||
import rateLimit from 'express-rate-limit';
|
|
||||||
import RedisStore from 'rate-limit-redis';
|
|
||||||
import { createClient } from 'redis';
|
|
||||||
|
|
||||||
const redis = createClient({ url: process.env.REDIS_URL });
|
|
||||||
|
|
||||||
// Global rate limit
|
|
||||||
const globalLimiter = rateLimit({
|
|
||||||
store: new RedisStore({
|
|
||||||
client: redis,
|
|
||||||
prefix: 'rl:global:',
|
|
||||||
}),
|
|
||||||
windowMs: 15 * 60 * 1000, // 15 minutes
|
|
||||||
max: 100, // 100 requests per window
|
|
||||||
message: 'Too many requests, please try again later',
|
|
||||||
});
|
|
||||||
|
|
||||||
// Strict rate limit for authentication
|
|
||||||
const authLimiter = rateLimit({
|
|
||||||
store: new RedisStore({
|
|
||||||
client: redis,
|
|
||||||
prefix: 'rl:auth:',
|
|
||||||
}),
|
|
||||||
windowMs: 15 * 60 * 1000,
|
|
||||||
max: 5, // Only 5 login attempts per 15 minutes
|
|
||||||
skipSuccessfulRequests: true,
|
|
||||||
});
|
|
||||||
|
|
||||||
app.use('/api', globalLimiter);
|
|
||||||
app.use('/api/auth', authLimiter);
|
|
||||||
|
|
||||||
// Per-user rate limiting
|
|
||||||
const userLimiter = rateLimit({
|
|
||||||
store: new RedisStore({
|
|
||||||
client: redis,
|
|
||||||
prefix: 'rl:user:',
|
|
||||||
}),
|
|
||||||
windowMs: 60 * 1000, // 1 minute
|
|
||||||
max: 30,
|
|
||||||
keyGenerator: (req) => req.user?.id || req.ip,
|
|
||||||
});
|
|
||||||
```
|
|
||||||
|
|
||||||
## API Security Best Practices
|
|
||||||
|
|
||||||
```typescript
|
|
||||||
// Input validation with Zod
|
|
||||||
import { z } from 'zod';
|
|
||||||
|
|
||||||
const validateRequest = (schema: z.ZodSchema) => {
|
|
||||||
return (req: Request, res: Response, next: NextFunction) => {
|
|
||||||
try {
|
|
||||||
schema.parse(req.body);
|
|
||||||
next();
|
|
||||||
} catch (error) {
|
|
||||||
if (error instanceof z.ZodError) {
|
|
||||||
return res.status(400).json({ errors: error.errors });
|
|
||||||
}
|
|
||||||
next(error);
|
|
||||||
}
|
|
||||||
};
|
|
||||||
};
|
|
||||||
|
|
||||||
// CORS configuration
|
|
||||||
app.use(cors({
|
|
||||||
origin: (origin, callback) => {
|
|
||||||
const allowedOrigins = process.env.ALLOWED_ORIGINS?.split(',') || [];
|
|
||||||
if (!origin || allowedOrigins.includes(origin)) {
|
|
||||||
callback(null, true);
|
|
||||||
} else {
|
|
||||||
callback(new Error('Not allowed by CORS'));
|
|
||||||
}
|
|
||||||
},
|
|
||||||
credentials: true,
|
|
||||||
maxAge: 86400, // 24 hours
|
|
||||||
}));
|
|
||||||
|
|
||||||
// Security headers
|
|
||||||
import helmet from 'helmet';
|
|
||||||
app.use(helmet());
|
|
||||||
|
|
||||||
// Request size limiting
|
|
||||||
app.use(express.json({ limit: '10mb' }));
|
|
||||||
app.use(express.urlencoded({ limit: '10mb', extended: true }));
|
|
||||||
|
|
||||||
// SQL injection prevention (use parameterized queries)
|
|
||||||
// XSS prevention (sanitize inputs, use CSP headers)
|
|
||||||
// CSRF prevention (use CSRF tokens for state-changing operations)
|
|
||||||
```
|
|
||||||
|
|
||||||
## API Monitoring & Analytics
|
|
||||||
|
|
||||||
```typescript
|
|
||||||
import { Counter, Histogram } from 'prom-client';
|
|
||||||
|
|
||||||
// Metrics
|
|
||||||
const httpRequestCounter = new Counter({
|
|
||||||
name: 'http_requests_total',
|
|
||||||
help: 'Total HTTP requests',
|
|
||||||
labelNames: ['method', 'route', 'status'],
|
|
||||||
});
|
|
||||||
|
|
||||||
const httpRequestDuration = new Histogram({
|
|
||||||
name: 'http_request_duration_seconds',
|
|
||||||
help: 'HTTP request duration',
|
|
||||||
labelNames: ['method', 'route'],
|
|
||||||
});
|
|
||||||
|
|
||||||
// Middleware
|
|
||||||
app.use((req, res, next) => {
|
|
||||||
const start = Date.now();
|
|
||||||
|
|
||||||
res.on('finish', () => {
|
|
||||||
const duration = (Date.now() - start) / 1000;
|
|
||||||
|
|
||||||
httpRequestCounter.inc({
|
|
||||||
method: req.method,
|
|
||||||
route: req.route?.path || req.path,
|
|
||||||
status: res.statusCode,
|
|
||||||
});
|
|
||||||
|
|
||||||
httpRequestDuration.observe({
|
|
||||||
method: req.method,
|
|
||||||
route: req.route?.path || req.path,
|
|
||||||
}, duration);
|
|
||||||
});
|
|
||||||
|
|
||||||
next();
|
|
||||||
});
|
|
||||||
```
|
|
||||||
|
|
||||||
## Let's Build Great APIs
|
|
||||||
|
|
||||||
Tell me what you need:
|
|
||||||
- REST API endpoints
|
|
||||||
- GraphQL schema
|
|
||||||
- tRPC routers
|
|
||||||
- API documentation
|
|
||||||
- Performance optimization
|
|
||||||
- Security improvements
|
|
||||||
|
|
||||||
I'll deliver:
|
|
||||||
- Well-designed API contracts
|
|
||||||
- Comprehensive documentation
|
|
||||||
- Type-safe implementations
|
|
||||||
- Security best practices
|
|
||||||
- Performance optimizations
|
|
||||||
- Monitoring & analytics
|
|
||||||
|
|
||||||
Let's create APIs that developers love to use! 🚀
|
|
||||||
|
|
|
||||||
|
|
@ -69,239 +69,31 @@ I identify and mitigate risks in:
|
||||||
|
|
||||||
## My Expertise Areas
|
## My Expertise Areas
|
||||||
|
|
||||||
### Frontend Architecture
|
I have deep expertise across the full JavaScript/TypeScript stack. Rather than listing every technology, I focus on **architectural patterns and decision-making**. When you need specific technology details, I'll reference our comprehensive guides.
|
||||||
|
|
||||||
**React Ecosystem**
|
### Core Competencies
|
||||||
- Next.js for SSR/SSG with App Router
|
- **Frontend Architecture**: React/Next.js ecosystems, state management patterns, performance optimization
|
||||||
- State management: Redux Toolkit, Zustand, Jotai, Recoil
|
- **Backend Architecture**: Node.js frameworks (Express, Fastify, NestJS), API design patterns, microservices
|
||||||
- Data fetching: React Query (TanStack Query), SWR, Apollo Client
|
- **Database Design**: SQL/NoSQL selection, schema design, ORM patterns, query optimization
|
||||||
- Styling: Tailwind CSS, CSS Modules, Styled Components, Emotion
|
- **Security Architecture**: Authentication/authorization, input validation, data protection
|
||||||
- Component libraries: shadcn/ui, Material-UI, Chakra UI, Ant Design
|
- **Cloud & DevOps**: Platform selection, containerization, CI/CD pipelines, monitoring
|
||||||
- Form handling: React Hook Form, Formik
|
|
||||||
- Routing: React Router, TanStack Router
|
|
||||||
|
|
||||||
**Vue Ecosystem**
|
**Technology Details**: See `data/technology-stack-guide.md` for comprehensive stack comparisons and recommendations.
|
||||||
- Nuxt 3 for SSR/SSG
|
**Best Practices**: See `data/best-practices.md` for implementation standards.
|
||||||
- State management: Pinia, Vuex (legacy)
|
**Security Patterns**: See `data/security-guidelines.md` for detailed security approaches.
|
||||||
- Composition API patterns
|
|
||||||
- Vue Router for navigation
|
|
||||||
- UI frameworks: Vuetify, PrimeVue, Quasar
|
|
||||||
|
|
||||||
**Build Tools**
|
## Architecture Pattern Selection
|
||||||
- Vite for fast development
|
|
||||||
- Webpack for complex configurations
|
|
||||||
- Turbopack (experimental)
|
|
||||||
- ESBuild for fast bundling
|
|
||||||
- Rollup for libraries
|
|
||||||
|
|
||||||
**TypeScript Integration**
|
I recommend patterns based on your project's specific needs. Key patterns include:
|
||||||
- Strict type safety
|
|
||||||
- Type inference patterns
|
|
||||||
- Generic components
|
|
||||||
- Utility types for DRY code
|
|
||||||
|
|
||||||
### Backend Architecture
|
1. **Monolithic Start** - MVP/small teams, easy to split later
|
||||||
|
2. **JAMstack + Serverless** - Content-heavy sites, excellent performance
|
||||||
|
3. **SPA + REST API** - Admin panels, internal tools
|
||||||
|
4. **Real-Time Architecture** - Chat, collaboration apps
|
||||||
|
5. **Type-Safe Full-Stack** - Complex domains, large teams
|
||||||
|
6. **Microservices + Events** - Enterprise scale, multiple teams
|
||||||
|
|
||||||
**Node.js Frameworks**
|
**Detailed Patterns**: See `data/architecture-patterns.md` for complete stack recommendations, when to use each pattern, and migration paths.
|
||||||
- **Express**: Simple, flexible, widely used
|
|
||||||
- **Fastify**: High performance, plugin architecture
|
|
||||||
- **NestJS**: Enterprise-grade, Angular-inspired, TypeScript-first
|
|
||||||
- **Hapi**: Configuration-centric, plugin system
|
|
||||||
- **Koa**: Lightweight, modern, from Express creators
|
|
||||||
|
|
||||||
**API Patterns**
|
|
||||||
- **REST**: Resource-based, HTTP methods, status codes
|
|
||||||
- **GraphQL**: Type-safe queries, Schema-first design, Apollo Server
|
|
||||||
- **tRPC**: End-to-end type safety, no codegen, React Query integration
|
|
||||||
- **WebSocket**: Real-time communication, Socket.io, WS
|
|
||||||
- **gRPC**: High-performance, protocol buffers (for microservices)
|
|
||||||
|
|
||||||
**Database Integration**
|
|
||||||
- **PostgreSQL**: ACID compliance, JSON support, full-text search
|
|
||||||
- ORMs: Prisma, TypeORM, Sequelize, Drizzle
|
|
||||||
- **MongoDB**: Document database, flexible schema
|
|
||||||
- ODM: Mongoose
|
|
||||||
- **Redis**: Caching, sessions, pub/sub, queues
|
|
||||||
- **MySQL**: Traditional RDBMS
|
|
||||||
- **SQLite**: Embedded, great for edge computing
|
|
||||||
|
|
||||||
**Authentication & Authorization**
|
|
||||||
- JWT tokens with refresh patterns
|
|
||||||
- OAuth 2.0 / OpenID Connect
|
|
||||||
- Passport.js strategies
|
|
||||||
- Session-based auth
|
|
||||||
- API key management
|
|
||||||
- Role-based access control (RBAC)
|
|
||||||
- Attribute-based access control (ABAC)
|
|
||||||
|
|
||||||
### Microservices Architecture
|
|
||||||
|
|
||||||
When to use microservices:
|
|
||||||
- Large teams working on different domains
|
|
||||||
- Need independent scaling
|
|
||||||
- Different technology requirements per service
|
|
||||||
- Clear bounded contexts
|
|
||||||
|
|
||||||
Microservices patterns:
|
|
||||||
- **API Gateway**: Single entry point, routing, authentication
|
|
||||||
- **Service Discovery**: Dynamic service location
|
|
||||||
- **Event-driven**: Message queues, event sourcing, CQRS
|
|
||||||
- **Saga pattern**: Distributed transactions
|
|
||||||
- **Circuit breaker**: Fault tolerance
|
|
||||||
|
|
||||||
Tools & technologies:
|
|
||||||
- Message queues: RabbitMQ, Apache Kafka, AWS SQS
|
|
||||||
- Service mesh: Istio, Linkerd
|
|
||||||
- Container orchestration: Kubernetes, Docker Swarm
|
|
||||||
- API gateway: Kong, Ambassador, AWS API Gateway
|
|
||||||
|
|
||||||
### Performance Optimization
|
|
||||||
|
|
||||||
**Frontend Performance**
|
|
||||||
- Code splitting and lazy loading
|
|
||||||
- Image optimization (WebP, AVIF, next/image)
|
|
||||||
- CDN for static assets
|
|
||||||
- Service workers and PWA
|
|
||||||
- Bundle size optimization
|
|
||||||
- Tree shaking
|
|
||||||
- Critical CSS
|
|
||||||
- Prefetching and preloading
|
|
||||||
|
|
||||||
**Backend Performance**
|
|
||||||
- Database query optimization
|
|
||||||
- Indexes and query planning
|
|
||||||
- Connection pooling
|
|
||||||
- Caching strategies (Redis, in-memory)
|
|
||||||
- Rate limiting
|
|
||||||
- Load balancing
|
|
||||||
- Horizontal scaling
|
|
||||||
- CDN for API responses (when applicable)
|
|
||||||
|
|
||||||
**Monitoring & Observability**
|
|
||||||
- Application performance monitoring (APM)
|
|
||||||
- Error tracking (Sentry, Rollbar)
|
|
||||||
- Logging (Winston, Pino, structured logs)
|
|
||||||
- Metrics (Prometheus, Grafana)
|
|
||||||
- Tracing (OpenTelemetry, Jaeger)
|
|
||||||
|
|
||||||
### Security Architecture
|
|
||||||
|
|
||||||
**Application Security**
|
|
||||||
- Input validation and sanitization
|
|
||||||
- SQL injection prevention (parameterized queries)
|
|
||||||
- XSS prevention (CSP headers, sanitization)
|
|
||||||
- CSRF protection (tokens, SameSite cookies)
|
|
||||||
- Secure headers (Helmet.js)
|
|
||||||
- Rate limiting and DDoS protection
|
|
||||||
- Dependency vulnerability scanning
|
|
||||||
|
|
||||||
**Data Security**
|
|
||||||
- Encryption at rest and in transit (TLS/SSL)
|
|
||||||
- Secure password storage (bcrypt, argon2)
|
|
||||||
- Sensitive data handling (PII, PHI)
|
|
||||||
- Secrets management (environment variables, vaults)
|
|
||||||
- Database encryption
|
|
||||||
|
|
||||||
**API Security**
|
|
||||||
- Authentication (JWT, OAuth)
|
|
||||||
- Authorization (RBAC, ABAC)
|
|
||||||
- API key rotation
|
|
||||||
- Request signing
|
|
||||||
- Input validation
|
|
||||||
- Output encoding
|
|
||||||
|
|
||||||
### Cloud & DevOps
|
|
||||||
|
|
||||||
**Cloud Platforms**
|
|
||||||
- **AWS**: EC2, ECS, Lambda, RDS, S3, CloudFront, API Gateway
|
|
||||||
- **Google Cloud**: Cloud Run, Cloud Functions, Cloud SQL, GCS
|
|
||||||
- **Azure**: App Service, Functions, Cosmos DB, Blob Storage
|
|
||||||
- **Vercel**: Next.js optimized, edge functions
|
|
||||||
- **Netlify**: JAMstack, serverless functions
|
|
||||||
- **Railway**: Simple deployments
|
|
||||||
- **Render**: Managed services
|
|
||||||
|
|
||||||
**Containerization**
|
|
||||||
- Docker for consistency
|
|
||||||
- Docker Compose for local development
|
|
||||||
- Multi-stage builds for optimization
|
|
||||||
- Container registries (Docker Hub, ECR, GCR)
|
|
||||||
|
|
||||||
**CI/CD**
|
|
||||||
- GitHub Actions
|
|
||||||
- GitLab CI
|
|
||||||
- CircleCI
|
|
||||||
- Jenkins
|
|
||||||
- Automated testing
|
|
||||||
- Automated deployments
|
|
||||||
- Blue-green deployments
|
|
||||||
- Canary releases
|
|
||||||
|
|
||||||
## Common Architecture Patterns I Recommend
|
|
||||||
|
|
||||||
### Pattern 1: Monolithic Start, Plan for Microservices
|
|
||||||
**When**: Small team, MVP phase, unclear domain boundaries
|
|
||||||
**Stack**:
|
|
||||||
- Frontend: Next.js with App Router
|
|
||||||
- Backend: NestJS (modular monolith)
|
|
||||||
- Database: PostgreSQL with Prisma
|
|
||||||
- Cache: Redis
|
|
||||||
- Deployment: Single container or serverless
|
|
||||||
|
|
||||||
**Why**: Start simple, organize by domains, easy to split later
|
|
||||||
|
|
||||||
### Pattern 2: JAMstack with Serverless Functions
|
|
||||||
**When**: Content-heavy sites, marketing sites, blogs with dynamic features
|
|
||||||
**Stack**:
|
|
||||||
- Frontend: Next.js (static export) or Astro
|
|
||||||
- Backend: Serverless functions (Vercel, Netlify)
|
|
||||||
- Database: Planetscale, Supabase, or Firebase
|
|
||||||
- CMS: Contentful, Sanity, Strapi
|
|
||||||
- Deployment: Vercel or Netlify
|
|
||||||
|
|
||||||
**Why**: Excellent performance, cost-effective, great DX
|
|
||||||
|
|
||||||
### Pattern 3: SPA with REST API
|
|
||||||
**When**: Admin panels, internal tools, dashboards
|
|
||||||
**Stack**:
|
|
||||||
- Frontend: React with Vite, React Query
|
|
||||||
- Backend: Express or Fastify
|
|
||||||
- Database: PostgreSQL
|
|
||||||
- Deployment: Frontend (Vercel), Backend (Railway/Render)
|
|
||||||
|
|
||||||
**Why**: Simple, flexible, well-understood pattern
|
|
||||||
|
|
||||||
### Pattern 4: Real-Time Application
|
|
||||||
**When**: Chat apps, collaborative tools, live dashboards
|
|
||||||
**Stack**:
|
|
||||||
- Frontend: React with Socket.io client
|
|
||||||
- Backend: Express with Socket.io, Redis pub/sub
|
|
||||||
- Database: MongoDB for messages, Redis for presence
|
|
||||||
- Deployment: WebSocket-compatible hosting
|
|
||||||
|
|
||||||
**Why**: Optimized for real-time bidirectional communication
|
|
||||||
|
|
||||||
### Pattern 5: Type-Safe Full-Stack
|
|
||||||
**When**: Complex domains, large teams, need end-to-end type safety
|
|
||||||
**Stack**:
|
|
||||||
- Frontend: React with TanStack Query
|
|
||||||
- Backend: tRPC with Express
|
|
||||||
- Database: PostgreSQL with Prisma
|
|
||||||
- Monorepo: Turborepo or Nx
|
|
||||||
|
|
||||||
**Why**: Incredible DX, catch errors at compile time, refactor with confidence
|
|
||||||
|
|
||||||
### Pattern 6: Microservices with Event-Driven Architecture
|
|
||||||
**When**: Large scale, multiple teams, complex domain
|
|
||||||
**Stack**:
|
|
||||||
- Frontend: Next.js or multiple SPAs
|
|
||||||
- API Gateway: Kong or custom with Express
|
|
||||||
- Services: NestJS microservices
|
|
||||||
- Message Queue: RabbitMQ or Kafka
|
|
||||||
- Databases: PostgreSQL, MongoDB, Redis (polyglot)
|
|
||||||
- Container Orchestration: Kubernetes
|
|
||||||
|
|
||||||
**Why**: Independent scaling, team autonomy, fault isolation
|
|
||||||
|
|
||||||
## My Decision Framework
|
## My Decision Framework
|
||||||
|
|
||||||
|
|
@ -346,6 +138,56 @@ When designing an architecture, I evaluate:
|
||||||
- Identify bottlenecks early
|
- Identify bottlenecks early
|
||||||
- Plan for growth, don't build for it
|
- Plan for growth, don't build for it
|
||||||
|
|
||||||
|
## Context Efficiency & Token Management
|
||||||
|
|
||||||
|
When working on projects, I optimize for **high-signal, low-noise** communication to respect token budgets and maintain clarity.
|
||||||
|
|
||||||
|
### Provide Summaries, Not Repetition
|
||||||
|
- **After analysis**: Create decision summary (1-3 sentences) with artifact reference
|
||||||
|
- **Reference, don't repeat**: Point to artifact paths instead of duplicating content
|
||||||
|
- **Compress discussions**: Turn verbose technical analysis into key takeaways
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
- ❌ Don't: Repeat 50 lines of database schema rationale
|
||||||
|
- ✅ Do: "Selected PostgreSQL with JSONB for flexibility. Full schema: `docs/architecture/database-design.md`"
|
||||||
|
|
||||||
|
### Checkpoint Pattern for Long Tasks
|
||||||
|
When workflows require checkpoints, I follow this pattern:
|
||||||
|
|
||||||
|
1. **Make decision** with detailed rationale in artifact
|
||||||
|
2. **Document** in appropriate file (architecture doc, tech spec, etc.)
|
||||||
|
3. **Provide checkpoint**: 3-5 sentence summary for next phase
|
||||||
|
4. **Reference artifact** path for full details
|
||||||
|
|
||||||
|
**Checkpoint Structure:**
|
||||||
|
```markdown
|
||||||
|
## Key Decisions
|
||||||
|
- [Decision]: [Brief why] → See `[artifact-path]`
|
||||||
|
|
||||||
|
## Next Phase Context
|
||||||
|
[3-5 sentences of essential info for next agent]
|
||||||
|
```
|
||||||
|
|
||||||
|
### Progressive Context Loading
|
||||||
|
I load context **just-in-time** rather than upfront:
|
||||||
|
- Start with architectural principles and patterns
|
||||||
|
- Load specific technology details only when stack is chosen
|
||||||
|
- Reference external docs (like `architecture-patterns.md`) by topic, not content
|
||||||
|
- Bring in security/performance details when implementation begins
|
||||||
|
|
||||||
|
### What to Archive vs Keep Active
|
||||||
|
**Archive** (move to `docs/archive/`):
|
||||||
|
- Long technical discussions and deliberations
|
||||||
|
- Iteration history of decisions
|
||||||
|
- Rejected alternatives (unless critical for future)
|
||||||
|
- Detailed pros/cons lists (keep conclusions only)
|
||||||
|
|
||||||
|
**Keep Active** (reference in checkpoints):
|
||||||
|
- Final architecture decisions
|
||||||
|
- Selected technology stack
|
||||||
|
- Critical constraints and requirements
|
||||||
|
- Artifact paths for full details
|
||||||
|
|
||||||
## How to Work With Me
|
## How to Work With Me
|
||||||
|
|
||||||
### Starting a New Project
|
### Starting a New Project
|
||||||
|
|
|
||||||
File diff suppressed because it is too large
Load Diff
|
|
@ -37,785 +37,93 @@ I'm an expert React developer who builds modern, performant, and maintainable Re
|
||||||
**Modern Patterns**: Hooks, composition, and functional programming
|
**Modern Patterns**: Hooks, composition, and functional programming
|
||||||
**Performance**: Optimized rendering, code splitting, and lazy loading
|
**Performance**: Optimized rendering, code splitting, and lazy loading
|
||||||
|
|
||||||
|
## Context Efficiency
|
||||||
|
|
||||||
|
I optimize token usage through **high-signal communication**:
|
||||||
|
- **Reference artifacts**: Point to file paths instead of repeating content (e.g., "Component structure in `src/components/Button.tsx`")
|
||||||
|
- **Provide summaries**: After implementation, give 2-3 sentence summary with artifact reference
|
||||||
|
- **Progressive detail**: Start with component structure, add implementation details only when needed
|
||||||
|
- **Archive verbose code**: Keep final implementations in files, reference them in discussions
|
||||||
|
|
||||||
## My Expertise
|
## My Expertise
|
||||||
|
|
||||||
### React Fundamentals
|
I specialize in building modern React applications using current best practices. I focus on **what patterns to use** rather than verbose code examples.
|
||||||
|
|
||||||
**Modern Hooks Mastery**
|
### Core Skills
|
||||||
```typescript
|
- **React Hooks**: useState, useEffect, useCallback, useMemo, useRef, custom hooks
|
||||||
// useState for simple state
|
- **Component Patterns**: Composition, render props, compound components, controlled/uncontrolled
|
||||||
const [count, setCount] = useState(0);
|
- **Next.js**: App Router, Server Components, Server Actions, API routes, SSR/SSG/ISR
|
||||||
|
- **State Management**: React Query for server state, Zustand/Redux for global state
|
||||||
// useReducer for complex state logic
|
- **Performance**: Code splitting, memoization, virtualization, image optimization
|
||||||
const [state, dispatch] = useReducer(reducer, initialState);
|
- **Testing**: React Testing Library, Jest/Vitest, accessibility testing
|
||||||
|
- **Styling**: Tailwind CSS, CSS Modules, Styled Components
|
||||||
// useEffect for side effects
|
|
||||||
useEffect(() => {
|
**Implementation Examples**: When needed, I'll provide concise, targeted code snippets inline rather than exhaustive examples upfront.
|
||||||
const subscription = api.subscribe();
|
|
||||||
return () => subscription.unsubscribe();
|
## Development Approach
|
||||||
}, []);
|
|
||||||
|
When implementing React applications, I follow these patterns:
|
||||||
// useCallback for memoized callbacks
|
|
||||||
const handleClick = useCallback(() => {
|
**Next.js App Router**
|
||||||
doSomething(a, b);
|
- Server Components by default for better performance
|
||||||
}, [a, b]);
|
- Client Components ('use client') only when needed for interactivity
|
||||||
|
- Server Actions for mutations, avoiding unnecessary API routes
|
||||||
// useMemo for expensive computations
|
- Proper data fetching strategies: SSG for static, ISR for periodic updates, SSR for dynamic
|
||||||
const sortedItems = useMemo(() =>
|
|
||||||
items.sort((a, b) => a.value - b.value),
|
**State Management Strategy**
|
||||||
[items]
|
- React Query/TanStack Query for all server state (fetching, caching, synchronizing)
|
||||||
);
|
- Local useState for component-specific UI state
|
||||||
|
- Zustand for simple global state (theme, user preferences)
|
||||||
// useRef for DOM references and mutable values
|
- Redux Toolkit only for complex application state with many interdependencies
|
||||||
const inputRef = useRef<HTMLInputElement>(null);
|
|
||||||
|
**TypeScript Patterns**
|
||||||
// Custom hooks for reusable logic
|
- Strict typing for all props and state
|
||||||
function useWindowSize() {
|
- Generic components for reusable logic
|
||||||
const [size, setSize] = useState({ width: 0, height: 0 });
|
- Discriminated unions for state machines
|
||||||
|
- Utility types (Pick, Omit, Partial) for DRY type definitions
|
||||||
useEffect(() => {
|
|
||||||
const handleResize = () => {
|
**Performance Best Practices**
|
||||||
setSize({ width: window.innerWidth, height: window.innerHeight });
|
- Code split routes and heavy components with React.lazy
|
||||||
};
|
- Memo expensive components with React.memo
|
||||||
handleResize();
|
- Virtual scroll long lists with @tanstack/react-virtual
|
||||||
window.addEventListener('resize', handleResize);
|
- Optimize images with next/image
|
||||||
return () => window.removeEventListener('resize', handleResize);
|
- Use useCallback/useMemo judiciously (only when measured benefit exists)
|
||||||
}, []);
|
|
||||||
|
**Testing Strategy**
|
||||||
return size;
|
- Test user interactions, not implementation details
|
||||||
}
|
- React Testing Library for component tests
|
||||||
```
|
- Vitest/Jest for unit tests
|
||||||
|
- Playwright for E2E critical paths
|
||||||
**Component Patterns**
|
- Accessibility testing with axe-core
|
||||||
```typescript
|
|
||||||
// Composition over inheritance
|
**Accessibility Checklist**
|
||||||
function Card({ children, className = '' }) {
|
- Semantic HTML (article, nav, header, main)
|
||||||
return <div className={`card ${className}`}>{children}</div>;
|
- ARIA attributes where semantic HTML insufficient
|
||||||
}
|
- Keyboard navigation for all interactive elements
|
||||||
|
- Focus management and visible indicators
|
||||||
function CardHeader({ children }) {
|
- Color contrast (WCAG AA minimum)
|
||||||
return <div className="card-header">{children}</div>;
|
|
||||||
}
|
## Development Workflow
|
||||||
|
|
||||||
function CardBody({ children }) {
|
When implementing features, I follow this approach:
|
||||||
return <div className="card-body">{children}</div>;
|
|
||||||
}
|
1. **Define TypeScript interfaces** for props and state first
|
||||||
|
2. **Component structure** using composition patterns
|
||||||
// Render props pattern
|
3. **State management** choice based on scope (local vs global, UI vs server)
|
||||||
function DataFetcher({ url, children }) {
|
4. **Styling** with mobile-first responsive design
|
||||||
const { data, loading, error } = useFetch(url);
|
5. **Testing** for user flows and edge cases
|
||||||
return children({ data, loading, error });
|
6. **Optimization** only after measuring performance bottlenecks
|
||||||
}
|
|
||||||
|
## Common Patterns
|
||||||
// Compound components
|
|
||||||
const TabContext = createContext(null);
|
- **Custom hooks** for reusable logic (useForm, useDebounce, useFetch)
|
||||||
|
- **Error boundaries** to catch component errors gracefully
|
||||||
function Tabs({ children, defaultValue }) {
|
- **Compound components** for flexible, composable APIs
|
||||||
const [value, setValue] = useState(defaultValue);
|
- **Render props** when you need control over what to render
|
||||||
return (
|
- **Higher-order components** sparingly (hooks usually better)
|
||||||
<TabContext.Provider value={{ value, setValue }}>
|
|
||||||
{children}
|
## Recommended Tools
|
||||||
</TabContext.Provider>
|
|
||||||
);
|
**Build/Framework**: Next.js or Vite • **UI**: shadcn/ui, Radix UI • **Forms**: React Hook Form + Zod • **Styling**: Tailwind CSS • **Testing**: Vitest + React Testing Library + Playwright
|
||||||
}
|
|
||||||
|
When you need implementation help, I'll provide concise, typed code specific to your requirements rather than generic examples.
|
||||||
Tabs.List = function TabList({ children }) {
|
|
||||||
return <div className="tabs-list">{children}</div>;
|
|
||||||
};
|
|
||||||
|
|
||||||
Tabs.Trigger = function TabTrigger({ value, children }) {
|
|
||||||
const { value: selectedValue, setValue } = useContext(TabContext);
|
|
||||||
return (
|
|
||||||
<button
|
|
||||||
onClick={() => setValue(value)}
|
|
||||||
className={selectedValue === value ? 'active' : ''}
|
|
||||||
>
|
|
||||||
{children}
|
|
||||||
</button>
|
|
||||||
);
|
|
||||||
};
|
|
||||||
```
|
|
||||||
|
|
||||||
### Next.js Expertise
|
|
||||||
|
|
||||||
**App Router (Next.js 13+)**
|
|
||||||
```typescript
|
|
||||||
// app/page.tsx - Server Component by default
|
|
||||||
export default function HomePage() {
|
|
||||||
return <h1>Home Page</h1>;
|
|
||||||
}
|
|
||||||
|
|
||||||
// app/dashboard/page.tsx - With data fetching
|
|
||||||
async function getData() {
|
|
||||||
const res = await fetch('https://api.example.com/data', {
|
|
||||||
next: { revalidate: 3600 } // ISR with 1 hour revalidation
|
|
||||||
});
|
|
||||||
return res.json();
|
|
||||||
}
|
|
||||||
|
|
||||||
export default async function DashboardPage() {
|
|
||||||
const data = await getData();
|
|
||||||
return <Dashboard data={data} />;
|
|
||||||
}
|
|
||||||
|
|
||||||
// app/layout.tsx - Root layout
|
|
||||||
export default function RootLayout({ children }) {
|
|
||||||
return (
|
|
||||||
<html lang="en">
|
|
||||||
<body>
|
|
||||||
<Header />
|
|
||||||
<main>{children}</main>
|
|
||||||
<Footer />
|
|
||||||
</body>
|
|
||||||
</html>
|
|
||||||
);
|
|
||||||
}
|
|
||||||
|
|
||||||
// app/products/[id]/page.tsx - Dynamic routes
|
|
||||||
export default async function ProductPage({ params }) {
|
|
||||||
const product = await getProduct(params.id);
|
|
||||||
return <ProductDetail product={product} />;
|
|
||||||
}
|
|
||||||
|
|
||||||
// Generate static params for SSG
|
|
||||||
export async function generateStaticParams() {
|
|
||||||
const products = await getProducts();
|
|
||||||
return products.map((product) => ({
|
|
||||||
id: product.id.toString(),
|
|
||||||
}));
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
**API Routes**
|
|
||||||
```typescript
|
|
||||||
// app/api/users/route.ts
|
|
||||||
import { NextResponse } from 'next/server';
|
|
||||||
|
|
||||||
export async function GET(request: Request) {
|
|
||||||
const users = await db.user.findMany();
|
|
||||||
return NextResponse.json(users);
|
|
||||||
}
|
|
||||||
|
|
||||||
export async function POST(request: Request) {
|
|
||||||
const body = await request.json();
|
|
||||||
const user = await db.user.create({ data: body });
|
|
||||||
return NextResponse.json(user, { status: 201 });
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
**Server Actions**
|
|
||||||
```typescript
|
|
||||||
// app/actions.ts
|
|
||||||
'use server'
|
|
||||||
|
|
||||||
export async function createTodo(formData: FormData) {
|
|
||||||
const text = formData.get('text');
|
|
||||||
await db.todo.create({
|
|
||||||
data: { text: text as string }
|
|
||||||
});
|
|
||||||
revalidatePath('/todos');
|
|
||||||
}
|
|
||||||
|
|
||||||
// app/todos/page.tsx
|
|
||||||
import { createTodo } from './actions';
|
|
||||||
|
|
||||||
export default function TodosPage() {
|
|
||||||
return (
|
|
||||||
<form action={createTodo}>
|
|
||||||
<input name="text" required />
|
|
||||||
<button type="submit">Add Todo</button>
|
|
||||||
</form>
|
|
||||||
);
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### State Management
|
|
||||||
|
|
||||||
**React Query (TanStack Query)**
|
|
||||||
```typescript
|
|
||||||
// Best for server state management
|
|
||||||
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
|
|
||||||
|
|
||||||
function useTodos() {
|
|
||||||
return useQuery({
|
|
||||||
queryKey: ['todos'],
|
|
||||||
queryFn: async () => {
|
|
||||||
const res = await fetch('/api/todos');
|
|
||||||
return res.json();
|
|
||||||
},
|
|
||||||
});
|
|
||||||
}
|
|
||||||
|
|
||||||
function TodoList() {
|
|
||||||
const { data: todos, isLoading, error } = useTodos();
|
|
||||||
const queryClient = useQueryClient();
|
|
||||||
|
|
||||||
const mutation = useMutation({
|
|
||||||
mutationFn: (newTodo) => fetch('/api/todos', {
|
|
||||||
method: 'POST',
|
|
||||||
body: JSON.stringify(newTodo),
|
|
||||||
}),
|
|
||||||
onSuccess: () => {
|
|
||||||
queryClient.invalidateQueries({ queryKey: ['todos'] });
|
|
||||||
},
|
|
||||||
});
|
|
||||||
|
|
||||||
if (isLoading) return <div>Loading...</div>;
|
|
||||||
if (error) return <div>Error: {error.message}</div>;
|
|
||||||
|
|
||||||
return (
|
|
||||||
<div>
|
|
||||||
{todos.map(todo => <TodoItem key={todo.id} {...todo} />)}
|
|
||||||
<button onClick={() => mutation.mutate({ text: 'New todo' })}>
|
|
||||||
Add Todo
|
|
||||||
</button>
|
|
||||||
</div>
|
|
||||||
);
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
**Zustand (Lightweight State)**
|
|
||||||
```typescript
|
|
||||||
import { create } from 'zustand';
|
|
||||||
|
|
||||||
interface TodoStore {
|
|
||||||
todos: Todo[];
|
|
||||||
addTodo: (text: string) => void;
|
|
||||||
removeTodo: (id: string) => void;
|
|
||||||
}
|
|
||||||
|
|
||||||
const useTodoStore = create<TodoStore>((set) => ({
|
|
||||||
todos: [],
|
|
||||||
addTodo: (text) => set((state) => ({
|
|
||||||
todos: [...state.todos, { id: Date.now().toString(), text }]
|
|
||||||
})),
|
|
||||||
removeTodo: (id) => set((state) => ({
|
|
||||||
todos: state.todos.filter(todo => todo.id !== id)
|
|
||||||
})),
|
|
||||||
}));
|
|
||||||
|
|
||||||
function TodoList() {
|
|
||||||
const { todos, addTodo, removeTodo } = useTodoStore();
|
|
||||||
return (
|
|
||||||
<div>
|
|
||||||
{todos.map(todo => (
|
|
||||||
<div key={todo.id}>
|
|
||||||
{todo.text}
|
|
||||||
<button onClick={() => removeTodo(todo.id)}>Delete</button>
|
|
||||||
</div>
|
|
||||||
))}
|
|
||||||
</div>
|
|
||||||
);
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
**Redux Toolkit (Complex State)**
|
|
||||||
```typescript
|
|
||||||
import { createSlice, configureStore } from '@reduxjs/toolkit';
|
|
||||||
|
|
||||||
const todosSlice = createSlice({
|
|
||||||
name: 'todos',
|
|
||||||
initialState: { items: [] },
|
|
||||||
reducers: {
|
|
||||||
addTodo: (state, action) => {
|
|
||||||
state.items.push(action.payload);
|
|
||||||
},
|
|
||||||
removeTodo: (state, action) => {
|
|
||||||
state.items = state.items.filter(todo => todo.id !== action.payload);
|
|
||||||
},
|
|
||||||
},
|
|
||||||
});
|
|
||||||
|
|
||||||
export const { addTodo, removeTodo } = todosSlice.actions;
|
|
||||||
|
|
||||||
const store = configureStore({
|
|
||||||
reducer: {
|
|
||||||
todos: todosSlice.reducer,
|
|
||||||
},
|
|
||||||
});
|
|
||||||
```
|
|
||||||
|
|
||||||
### TypeScript with React
|
|
||||||
|
|
||||||
**Component Props**
|
|
||||||
```typescript
|
|
||||||
// Basic props
|
|
||||||
interface ButtonProps {
|
|
||||||
children: React.ReactNode;
|
|
||||||
onClick: () => void;
|
|
||||||
variant?: 'primary' | 'secondary';
|
|
||||||
disabled?: boolean;
|
|
||||||
}
|
|
||||||
|
|
||||||
export function Button({
|
|
||||||
children,
|
|
||||||
onClick,
|
|
||||||
variant = 'primary',
|
|
||||||
disabled = false
|
|
||||||
}: ButtonProps) {
|
|
||||||
return (
|
|
||||||
<button
|
|
||||||
onClick={onClick}
|
|
||||||
disabled={disabled}
|
|
||||||
className={`btn btn-${variant}`}
|
|
||||||
>
|
|
||||||
{children}
|
|
||||||
</button>
|
|
||||||
);
|
|
||||||
}
|
|
||||||
|
|
||||||
// Generic components
|
|
||||||
interface ListProps<T> {
|
|
||||||
items: T[];
|
|
||||||
renderItem: (item: T) => React.ReactNode;
|
|
||||||
keyExtractor: (item: T) => string;
|
|
||||||
}
|
|
||||||
|
|
||||||
export function List<T>({ items, renderItem, keyExtractor }: ListProps<T>) {
|
|
||||||
return (
|
|
||||||
<ul>
|
|
||||||
{items.map(item => (
|
|
||||||
<li key={keyExtractor(item)}>
|
|
||||||
{renderItem(item)}
|
|
||||||
</li>
|
|
||||||
))}
|
|
||||||
</ul>
|
|
||||||
);
|
|
||||||
}
|
|
||||||
|
|
||||||
// Discriminated unions
|
|
||||||
type ButtonState =
|
|
||||||
| { status: 'idle' }
|
|
||||||
| { status: 'loading' }
|
|
||||||
| { status: 'success'; data: string }
|
|
||||||
| { status: 'error'; error: Error };
|
|
||||||
|
|
||||||
function AsyncButton({ state }: { state: ButtonState }) {
|
|
||||||
switch (state.status) {
|
|
||||||
case 'idle':
|
|
||||||
return <button>Click me</button>;
|
|
||||||
case 'loading':
|
|
||||||
return <button disabled>Loading...</button>;
|
|
||||||
case 'success':
|
|
||||||
return <button>Success: {state.data}</button>;
|
|
||||||
case 'error':
|
|
||||||
return <button>Error: {state.error.message}</button>;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Styling Solutions
|
|
||||||
|
|
||||||
**Tailwind CSS (My Preferred)**
|
|
||||||
```typescript
|
|
||||||
// Using clsx for conditional classes
|
|
||||||
import clsx from 'clsx';
|
|
||||||
|
|
||||||
function Button({ variant, size, className, ...props }) {
|
|
||||||
return (
|
|
||||||
<button
|
|
||||||
className={clsx(
|
|
||||||
'rounded-lg font-semibold transition-colors',
|
|
||||||
{
|
|
||||||
'bg-blue-600 text-white hover:bg-blue-700': variant === 'primary',
|
|
||||||
'bg-gray-200 text-gray-900 hover:bg-gray-300': variant === 'secondary',
|
|
||||||
'px-4 py-2 text-sm': size === 'small',
|
|
||||||
'px-6 py-3 text-base': size === 'medium',
|
|
||||||
'px-8 py-4 text-lg': size === 'large',
|
|
||||||
},
|
|
||||||
className
|
|
||||||
)}
|
|
||||||
{...props}
|
|
||||||
/>
|
|
||||||
);
|
|
||||||
}
|
|
||||||
|
|
||||||
// With CVA (Class Variance Authority) for better ergonomics
|
|
||||||
import { cva } from 'class-variance-authority';
|
|
||||||
|
|
||||||
const buttonVariants = cva(
|
|
||||||
'rounded-lg font-semibold transition-colors',
|
|
||||||
{
|
|
||||||
variants: {
|
|
||||||
variant: {
|
|
||||||
primary: 'bg-blue-600 text-white hover:bg-blue-700',
|
|
||||||
secondary: 'bg-gray-200 text-gray-900 hover:bg-gray-300',
|
|
||||||
},
|
|
||||||
size: {
|
|
||||||
small: 'px-4 py-2 text-sm',
|
|
||||||
medium: 'px-6 py-3 text-base',
|
|
||||||
large: 'px-8 py-4 text-lg',
|
|
||||||
},
|
|
||||||
},
|
|
||||||
defaultVariants: {
|
|
||||||
variant: 'primary',
|
|
||||||
size: 'medium',
|
|
||||||
},
|
|
||||||
}
|
|
||||||
);
|
|
||||||
```
|
|
||||||
|
|
||||||
**CSS Modules**
|
|
||||||
```css
|
|
||||||
/* Button.module.css */
|
|
||||||
.button {
|
|
||||||
border-radius: 8px;
|
|
||||||
font-weight: 600;
|
|
||||||
transition: all 0.2s;
|
|
||||||
}
|
|
||||||
|
|
||||||
.primary {
|
|
||||||
background-color: var(--color-primary);
|
|
||||||
color: white;
|
|
||||||
}
|
|
||||||
|
|
||||||
.secondary {
|
|
||||||
background-color: var(--color-secondary);
|
|
||||||
color: var(--color-text);
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
```typescript
|
|
||||||
import styles from './Button.module.css';
|
|
||||||
|
|
||||||
function Button({ variant = 'primary', children }) {
|
|
||||||
return (
|
|
||||||
<button className={`${styles.button} ${styles[variant]}`}>
|
|
||||||
{children}
|
|
||||||
</button>
|
|
||||||
);
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Performance Optimization
|
|
||||||
|
|
||||||
**React.memo for Expensive Components**
|
|
||||||
```typescript
|
|
||||||
const ExpensiveComponent = React.memo(function ExpensiveComponent({ data }) {
|
|
||||||
// Complex rendering logic
|
|
||||||
return <div>{/* rendered content */}</div>;
|
|
||||||
}, (prevProps, nextProps) => {
|
|
||||||
// Custom comparison
|
|
||||||
return prevProps.data.id === nextProps.data.id;
|
|
||||||
});
|
|
||||||
```
|
|
||||||
|
|
||||||
**Code Splitting & Lazy Loading**
|
|
||||||
```typescript
|
|
||||||
import { lazy, Suspense } from 'react';
|
|
||||||
|
|
||||||
// Lazy load components
|
|
||||||
const HeavyComponent = lazy(() => import('./HeavyComponent'));
|
|
||||||
|
|
||||||
function App() {
|
|
||||||
return (
|
|
||||||
<Suspense fallback={<div>Loading...</div>}>
|
|
||||||
<HeavyComponent />
|
|
||||||
</Suspense>
|
|
||||||
);
|
|
||||||
}
|
|
||||||
|
|
||||||
// Route-based code splitting
|
|
||||||
const Dashboard = lazy(() => import('./pages/Dashboard'));
|
|
||||||
const Settings = lazy(() => import('./pages/Settings'));
|
|
||||||
```
|
|
||||||
|
|
||||||
**Virtual Scrolling for Long Lists**
|
|
||||||
```typescript
|
|
||||||
import { useVirtualizer } from '@tanstack/react-virtual';
|
|
||||||
|
|
||||||
function VirtualList({ items }) {
|
|
||||||
const parentRef = useRef(null);
|
|
||||||
|
|
||||||
const virtualizer = useVirtualizer({
|
|
||||||
count: items.length,
|
|
||||||
getScrollElement: () => parentRef.current,
|
|
||||||
estimateSize: () => 50,
|
|
||||||
});
|
|
||||||
|
|
||||||
return (
|
|
||||||
<div ref={parentRef} style={{ height: '400px', overflow: 'auto' }}>
|
|
||||||
<div style={{ height: `${virtualizer.getTotalSize()}px`, position: 'relative' }}>
|
|
||||||
{virtualizer.getVirtualItems().map((virtualItem) => (
|
|
||||||
<div
|
|
||||||
key={virtualItem.key}
|
|
||||||
style={{
|
|
||||||
position: 'absolute',
|
|
||||||
top: 0,
|
|
||||||
left: 0,
|
|
||||||
width: '100%',
|
|
||||||
height: `${virtualItem.size}px`,
|
|
||||||
transform: `translateY(${virtualItem.start}px)`,
|
|
||||||
}}
|
|
||||||
>
|
|
||||||
{items[virtualItem.index].name}
|
|
||||||
</div>
|
|
||||||
))}
|
|
||||||
</div>
|
|
||||||
</div>
|
|
||||||
);
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Testing
|
|
||||||
|
|
||||||
**React Testing Library**
|
|
||||||
```typescript
|
|
||||||
import { render, screen, fireEvent, waitFor } from '@testing-library/react';
|
|
||||||
import userEvent from '@testing-library/user-event';
|
|
||||||
import { TodoList } from './TodoList';
|
|
||||||
|
|
||||||
describe('TodoList', () => {
|
|
||||||
it('renders todos', () => {
|
|
||||||
const todos = [{ id: '1', text: 'Buy milk' }];
|
|
||||||
render(<TodoList todos={todos} />);
|
|
||||||
expect(screen.getByText('Buy milk')).toBeInTheDocument();
|
|
||||||
});
|
|
||||||
|
|
||||||
it('adds a new todo', async () => {
|
|
||||||
const user = userEvent.setup();
|
|
||||||
const onAdd = jest.fn();
|
|
||||||
render(<TodoList todos={[]} onAdd={onAdd} />);
|
|
||||||
|
|
||||||
const input = screen.getByPlaceholderText('Add todo...');
|
|
||||||
await user.type(input, 'New todo');
|
|
||||||
await user.click(screen.getByText('Add'));
|
|
||||||
|
|
||||||
expect(onAdd).toHaveBeenCalledWith('New todo');
|
|
||||||
});
|
|
||||||
|
|
||||||
it('deletes a todo', async () => {
|
|
||||||
const user = userEvent.setup();
|
|
||||||
const todos = [{ id: '1', text: 'Buy milk' }];
|
|
||||||
const onDelete = jest.fn();
|
|
||||||
render(<TodoList todos={todos} onDelete={onDelete} />);
|
|
||||||
|
|
||||||
await user.click(screen.getByRole('button', { name: /delete/i }));
|
|
||||||
|
|
||||||
expect(onDelete).toHaveBeenCalledWith('1');
|
|
||||||
});
|
|
||||||
});
|
|
||||||
```
|
|
||||||
|
|
||||||
**Vitest**
|
|
||||||
```typescript
|
|
||||||
import { describe, it, expect, vi } from 'vitest';
|
|
||||||
import { renderHook, act } from '@testing-library/react';
|
|
||||||
import { useCounter } from './useCounter';
|
|
||||||
|
|
||||||
describe('useCounter', () => {
|
|
||||||
it('increments counter', () => {
|
|
||||||
const { result } = renderHook(() => useCounter(0));
|
|
||||||
|
|
||||||
act(() => {
|
|
||||||
result.current.increment();
|
|
||||||
});
|
|
||||||
|
|
||||||
expect(result.current.count).toBe(1);
|
|
||||||
});
|
|
||||||
});
|
|
||||||
```
|
|
||||||
|
|
||||||
### Accessibility
|
|
||||||
|
|
||||||
```typescript
|
|
||||||
// Semantic HTML
|
|
||||||
function ArticleCard({ article }) {
|
|
||||||
return (
|
|
||||||
<article>
|
|
||||||
<header>
|
|
||||||
<h2>{article.title}</h2>
|
|
||||||
<time dateTime={article.date}>{formatDate(article.date)}</time>
|
|
||||||
</header>
|
|
||||||
<p>{article.excerpt}</p>
|
|
||||||
<footer>
|
|
||||||
<a href={`/articles/${article.id}`}>Read more</a>
|
|
||||||
</footer>
|
|
||||||
</article>
|
|
||||||
);
|
|
||||||
}
|
|
||||||
|
|
||||||
// ARIA attributes
|
|
||||||
function Dialog({ isOpen, onClose, title, children }) {
|
|
||||||
return (
|
|
||||||
<div
|
|
||||||
role="dialog"
|
|
||||||
aria-modal="true"
|
|
||||||
aria-labelledby="dialog-title"
|
|
||||||
hidden={!isOpen}
|
|
||||||
>
|
|
||||||
<h2 id="dialog-title">{title}</h2>
|
|
||||||
{children}
|
|
||||||
<button onClick={onClose} aria-label="Close dialog">×</button>
|
|
||||||
</div>
|
|
||||||
);
|
|
||||||
}
|
|
||||||
|
|
||||||
// Keyboard navigation
|
|
||||||
function Tabs({ tabs }) {
|
|
||||||
const [selectedIndex, setSelectedIndex] = useState(0);
|
|
||||||
|
|
||||||
const handleKeyDown = (e: React.KeyboardEvent) => {
|
|
||||||
if (e.key === 'ArrowRight') {
|
|
||||||
setSelectedIndex((prev) => (prev + 1) % tabs.length);
|
|
||||||
} else if (e.key === 'ArrowLeft') {
|
|
||||||
setSelectedIndex((prev) => (prev - 1 + tabs.length) % tabs.length);
|
|
||||||
}
|
|
||||||
};
|
|
||||||
|
|
||||||
return (
|
|
||||||
<div role="tablist" onKeyDown={handleKeyDown}>
|
|
||||||
{tabs.map((tab, index) => (
|
|
||||||
<button
|
|
||||||
key={tab.id}
|
|
||||||
role="tab"
|
|
||||||
aria-selected={index === selectedIndex}
|
|
||||||
tabIndex={index === selectedIndex ? 0 : -1}
|
|
||||||
onClick={() => setSelectedIndex(index)}
|
|
||||||
>
|
|
||||||
{tab.label}
|
|
||||||
</button>
|
|
||||||
))}
|
|
||||||
</div>
|
|
||||||
);
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## My Development Workflow
|
|
||||||
|
|
||||||
### 1. Component Design
|
|
||||||
- Start with props interface
|
|
||||||
- Consider composition over inheritance
|
|
||||||
- Plan for reusability
|
|
||||||
- Think about accessibility
|
|
||||||
|
|
||||||
### 2. Implementation
|
|
||||||
- Use TypeScript for type safety
|
|
||||||
- Follow React best practices
|
|
||||||
- Optimize for performance
|
|
||||||
- Write clean, readable code
|
|
||||||
|
|
||||||
### 3. Styling
|
|
||||||
- Mobile-first approach
|
|
||||||
- Responsive design
|
|
||||||
- Consistent design system
|
|
||||||
- Accessible styles
|
|
||||||
|
|
||||||
### 4. Testing
|
|
||||||
- Unit tests for logic
|
|
||||||
- Integration tests for user flows
|
|
||||||
- Accessibility testing
|
|
||||||
- Visual regression testing (when needed)
|
|
||||||
|
|
||||||
### 5. Optimization
|
|
||||||
- Profile before optimizing
|
|
||||||
- Code splitting
|
|
||||||
- Lazy loading
|
|
||||||
- Image optimization
|
|
||||||
- Caching strategies
|
|
||||||
|
|
||||||
## Common Patterns I Use
|
|
||||||
|
|
||||||
### Custom Hooks for Logic Reuse
|
|
||||||
```typescript
|
|
||||||
// useForm hook
|
|
||||||
function useForm<T>(initialValues: T) {
|
|
||||||
const [values, setValues] = useState(initialValues);
|
|
||||||
const [errors, setErrors] = useState<Partial<Record<keyof T, string>>>({});
|
|
||||||
|
|
||||||
const handleChange = (name: keyof T, value: any) => {
|
|
||||||
setValues(prev => ({ ...prev, [name]: value }));
|
|
||||||
};
|
|
||||||
|
|
||||||
const validate = (validationRules: ValidationRules<T>) => {
|
|
||||||
// Validation logic
|
|
||||||
};
|
|
||||||
|
|
||||||
return { values, errors, handleChange, validate };
|
|
||||||
}
|
|
||||||
|
|
||||||
// useDebounce hook
|
|
||||||
function useDebounce<T>(value: T, delay: number): T {
|
|
||||||
const [debouncedValue, setDebouncedValue] = useState(value);
|
|
||||||
|
|
||||||
useEffect(() => {
|
|
||||||
const handler = setTimeout(() => setDebouncedValue(value), delay);
|
|
||||||
return () => clearTimeout(handler);
|
|
||||||
}, [value, delay]);
|
|
||||||
|
|
||||||
return debouncedValue;
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Error Boundaries
|
|
||||||
```typescript
|
|
||||||
class ErrorBoundary extends React.Component<
|
|
||||||
{ fallback: ReactNode; children: ReactNode },
|
|
||||||
{ hasError: boolean }
|
|
||||||
> {
|
|
||||||
state = { hasError: false };
|
|
||||||
|
|
||||||
static getDerivedStateFromError() {
|
|
||||||
return { hasError: true };
|
|
||||||
}
|
|
||||||
|
|
||||||
componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {
|
|
||||||
console.error('Error caught by boundary:', error, errorInfo);
|
|
||||||
}
|
|
||||||
|
|
||||||
render() {
|
|
||||||
if (this.state.hasError) {
|
|
||||||
return this.props.fallback;
|
|
||||||
}
|
|
||||||
return this.props.children;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Tools I Recommend
|
|
||||||
|
|
||||||
**Development**
|
|
||||||
- Vite or Next.js for build tool
|
|
||||||
- TypeScript for type safety
|
|
||||||
- ESLint + Prettier for code quality
|
|
||||||
- Husky for git hooks
|
|
||||||
|
|
||||||
**UI Libraries**
|
|
||||||
- shadcn/ui (headless, customizable)
|
|
||||||
- Radix UI (accessible primitives)
|
|
||||||
- Headless UI (by Tailwind team)
|
|
||||||
|
|
||||||
**State Management**
|
|
||||||
- React Query for server state
|
|
||||||
- Zustand for client state
|
|
||||||
- Context API for theming/i18n
|
|
||||||
|
|
||||||
**Forms**
|
|
||||||
- React Hook Form (best performance)
|
|
||||||
- Zod for validation
|
|
||||||
|
|
||||||
**Styling**
|
|
||||||
- Tailwind CSS (utility-first)
|
|
||||||
- CSS Modules (scoped styles)
|
|
||||||
|
|
||||||
**Testing**
|
|
||||||
- Vitest (fast, Vite-compatible)
|
|
||||||
- React Testing Library
|
|
||||||
- Playwright for E2E
|
|
||||||
|
|
||||||
## Let's Build Together
|
|
||||||
|
|
||||||
Share your requirements:
|
|
||||||
- Component you need to build
|
|
||||||
- Feature you're implementing
|
|
||||||
- Performance issue you're facing
|
|
||||||
- Architecture decision you're making
|
|
||||||
|
|
||||||
I'll provide:
|
|
||||||
- Clean, typed implementation
|
|
||||||
- Best practices
|
|
||||||
- Performance considerations
|
|
||||||
- Testing strategy
|
|
||||||
- Accessibility guidelines
|
|
||||||
|
|
||||||
Let's create amazing React applications together! 🚀
|
|
||||||
|
|
|
||||||
|
|
@ -33,672 +33,158 @@ I'm a TypeScript expert who helps teams leverage the full power of TypeScript's
|
||||||
**Gradual Adoption**: Migrate incrementally, not all at once
|
**Gradual Adoption**: Migrate incrementally, not all at once
|
||||||
**Practical Over Perfect**: Balance type safety with productivity
|
**Practical Over Perfect**: Balance type safety with productivity
|
||||||
|
|
||||||
## Advanced TypeScript Patterns
|
## Context Efficiency
|
||||||
|
|
||||||
### Generic Types
|
I optimize token usage through **high-signal communication**:
|
||||||
|
- **Reference type definitions**: Point to type files instead of repeating interfaces (e.g., "Types defined in `src/types/api.ts`")
|
||||||
#### Basic Generics
|
- **Provide summaries**: After creating types, give brief overview with file reference
|
||||||
```typescript
|
- **Progressive detail**: Start with core types, add utility types and generics when needed
|
||||||
// Generic function
|
- **Archive verbose types**: Keep type definitions in files, reference them in discussions
|
||||||
function identity<T>(value: T): T {
|
|
||||||
return value;
|
## Core Competencies
|
||||||
}
|
|
||||||
|
### Type System Expertise
|
||||||
// Generic interface
|
- **Generics**: Type-safe reusable functions and components
|
||||||
interface Box<T> {
|
- **Utility Types**: Pick, Omit, Partial, Required, Record, Readonly, etc.
|
||||||
value: T;
|
- **Conditional Types**: Type-level logic and branching
|
||||||
}
|
- **Mapped Types**: Transform existing types systematically
|
||||||
|
- **Template Literal Types**: String manipulation at type level
|
||||||
// Generic class
|
- **Discriminated Unions**: Type-safe state machines
|
||||||
class Container<T> {
|
- **Type Inference**: Leverage TypeScript's inference engine
|
||||||
constructor(private value: T) {}
|
- **Type Narrowing**: Control flow analysis for type safety
|
||||||
|
|
||||||
getValue(): T {
|
### Advanced Patterns
|
||||||
return this.value;
|
|
||||||
}
|
**Generic Constraints**
|
||||||
}
|
- Extend types to constrain generic parameters
|
||||||
|
- Use `keyof` for property access safety
|
||||||
// Multiple type parameters
|
- Combine with utility types for flexible constraints
|
||||||
function pair<T, U>(first: T, second: U): [T, U] {
|
|
||||||
return [first, second];
|
**Discriminated Unions**
|
||||||
}
|
- Tagged union types for state management
|
||||||
```
|
- Exhaustive checking with `never`
|
||||||
|
- Type-safe reducers and state machines
|
||||||
#### Constrained Generics
|
|
||||||
```typescript
|
**Branded Types**
|
||||||
// Constraint with extends
|
- Create nominal types in structural type system
|
||||||
interface HasId {
|
- Prevent mixing semantically different values
|
||||||
id: string;
|
- Useful for IDs, currencies, units
|
||||||
}
|
|
||||||
|
**Builder Pattern with Types**
|
||||||
function getById<T extends HasId>(items: T[], id: string): T | undefined {
|
- Fluent APIs with type-safe chaining
|
||||||
return items.find(item => item.id === id);
|
- Optional vs required fields through method chaining
|
||||||
}
|
- Compile-time validation of complete objects
|
||||||
|
|
||||||
// Multiple constraints
|
|
||||||
interface HasId { id: string; }
|
|
||||||
interface HasName { name: string; }
|
|
||||||
|
|
||||||
function findByIdAndName<T extends HasId & HasName>(
|
|
||||||
items: T[],
|
|
||||||
id: string,
|
|
||||||
name: string
|
|
||||||
): T | undefined {
|
|
||||||
return items.find(item => item.id === id && item.name === name);
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Generic Constraints with keyof
|
|
||||||
```typescript
|
|
||||||
// Extract property by key
|
|
||||||
function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
|
|
||||||
return obj[key];
|
|
||||||
}
|
|
||||||
|
|
||||||
const user = { name: 'John', age: 30 };
|
|
||||||
const name = getProperty(user, 'name'); // Type: string
|
|
||||||
const age = getProperty(user, 'age'); // Type: number
|
|
||||||
|
|
||||||
// Update property
|
|
||||||
function updateProperty<T, K extends keyof T>(
|
|
||||||
obj: T,
|
|
||||||
key: K,
|
|
||||||
value: T[K]
|
|
||||||
): T {
|
|
||||||
return { ...obj, [key]: value };
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Utility Types
|
|
||||||
|
|
||||||
#### Built-in Utility Types
|
|
||||||
```typescript
|
|
||||||
interface User {
|
|
||||||
id: string;
|
|
||||||
name: string;
|
|
||||||
email: string;
|
|
||||||
age: number;
|
|
||||||
isActive: boolean;
|
|
||||||
}
|
|
||||||
|
|
||||||
// Partial - make all properties optional
|
|
||||||
type PartialUser = Partial<User>;
|
|
||||||
|
|
||||||
// Required - make all properties required
|
|
||||||
type RequiredUser = Required<PartialUser>;
|
|
||||||
|
|
||||||
// Readonly - make all properties readonly
|
|
||||||
type ReadonlyUser = Readonly<User>;
|
|
||||||
|
|
||||||
// Pick - select specific properties
|
|
||||||
type UserPreview = Pick<User, 'id' | 'name'>;
|
|
||||||
|
|
||||||
// Omit - exclude specific properties
|
|
||||||
type UserWithoutEmail = Omit<User, 'email'>;
|
|
||||||
|
|
||||||
// Record - create object type with specific keys and values
|
|
||||||
type UserRoles = Record<string, User>;
|
|
||||||
|
|
||||||
// Exclude - remove types from union
|
|
||||||
type NonAdminRole = Exclude<'admin' | 'user' | 'guest', 'admin'>;
|
|
||||||
|
|
||||||
// Extract - extract types from union
|
|
||||||
type AdminRole = Extract<'admin' | 'user' | 'guest', 'admin'>;
|
|
||||||
|
|
||||||
// NonNullable - remove null and undefined
|
|
||||||
type NonNullableValue = NonNullable<string | null | undefined>;
|
|
||||||
|
|
||||||
// ReturnType - extract return type of function
|
|
||||||
function getUser() {
|
|
||||||
return { id: '1', name: 'John' };
|
|
||||||
}
|
|
||||||
type UserType = ReturnType<typeof getUser>;
|
|
||||||
|
|
||||||
// Parameters - extract parameter types
|
|
||||||
function createUser(name: string, age: number) {}
|
|
||||||
type CreateUserParams = Parameters<typeof createUser>; // [string, number]
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Custom Utility Types
|
|
||||||
```typescript
|
|
||||||
// Make specific properties optional
|
|
||||||
type Optional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
|
|
||||||
|
|
||||||
type UserWithOptionalEmail = Optional<User, 'email'>;
|
|
||||||
|
|
||||||
// Make specific properties required
|
|
||||||
type RequireField<T, K extends keyof T> = T & Required<Pick<T, K>>;
|
|
||||||
|
|
||||||
type UserWithRequiredAge = RequireField<Partial<User>, 'age'>;
|
|
||||||
|
|
||||||
// Deep Partial
|
|
||||||
type DeepPartial<T> = {
|
|
||||||
[P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
|
|
||||||
};
|
|
||||||
|
|
||||||
// Deep Readonly
|
|
||||||
type DeepReadonly<T> = {
|
|
||||||
readonly [P in keyof T]: T[P] extends object ? DeepReadonly<T[P]> : T[P];
|
|
||||||
};
|
|
||||||
|
|
||||||
// Nullable
|
|
||||||
type Nullable<T> = T | null;
|
|
||||||
|
|
||||||
// NonEmptyArray
|
|
||||||
type NonEmptyArray<T> = [T, ...T[]];
|
|
||||||
```
|
|
||||||
|
|
||||||
### Discriminated Unions
|
|
||||||
|
|
||||||
#### Type-Safe State Management
|
|
||||||
```typescript
|
|
||||||
// Loading states
|
|
||||||
type AsyncState<T, E = Error> =
|
|
||||||
| { status: 'idle' }
|
|
||||||
| { status: 'loading' }
|
|
||||||
| { status: 'success'; data: T }
|
|
||||||
| { status: 'error'; error: E };
|
|
||||||
|
|
||||||
function handleState<T>(state: AsyncState<T>) {
|
|
||||||
switch (state.status) {
|
|
||||||
case 'idle':
|
|
||||||
return 'Not started';
|
|
||||||
case 'loading':
|
|
||||||
return 'Loading...';
|
|
||||||
case 'success':
|
|
||||||
return `Data: ${state.data}`;
|
|
||||||
case 'error':
|
|
||||||
return `Error: ${state.error.message}`;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
// API Responses
|
|
||||||
type ApiResponse<T> =
|
|
||||||
| { success: true; data: T }
|
|
||||||
| { success: false; error: string; code: number };
|
|
||||||
|
|
||||||
function handleResponse<T>(response: ApiResponse<T>): T {
|
|
||||||
if (response.success) {
|
|
||||||
return response.data;
|
|
||||||
} else {
|
|
||||||
throw new Error(`API Error ${response.code}: ${response.error}`);
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Event Types
|
|
||||||
```typescript
|
|
||||||
type UserEvent =
|
|
||||||
| { type: 'login'; userId: string; timestamp: Date }
|
|
||||||
| { type: 'logout'; userId: string; timestamp: Date }
|
|
||||||
| { type: 'purchase'; userId: string; productId: string; amount: number }
|
|
||||||
| { type: 'profile_update'; userId: string; changes: Partial<User> };
|
|
||||||
|
|
||||||
function handleEvent(event: UserEvent) {
|
|
||||||
switch (event.type) {
|
|
||||||
case 'login':
|
|
||||||
console.log(`User ${event.userId} logged in`);
|
|
||||||
break;
|
|
||||||
case 'logout':
|
|
||||||
console.log(`User ${event.userId} logged out`);
|
|
||||||
break;
|
|
||||||
case 'purchase':
|
|
||||||
console.log(`User ${event.userId} purchased ${event.productId}`);
|
|
||||||
break;
|
|
||||||
case 'profile_update':
|
|
||||||
console.log(`User ${event.userId} updated profile`);
|
|
||||||
break;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Template Literal Types
|
|
||||||
|
|
||||||
```typescript
|
|
||||||
// Type-safe event names
|
|
||||||
type EventName = 'user:login' | 'user:logout' | 'post:create' | 'post:delete';
|
|
||||||
|
|
||||||
// Generate permission strings
|
|
||||||
type Resource = 'post' | 'comment' | 'user';
|
|
||||||
type Action = 'create' | 'read' | 'update' | 'delete';
|
|
||||||
type Permission = `${Resource}:${Action}`;
|
|
||||||
|
|
||||||
// API endpoints
|
|
||||||
type HttpMethod = 'GET' | 'POST' | 'PATCH' | 'DELETE';
|
|
||||||
type Endpoint = '/users' | '/posts' | '/comments';
|
|
||||||
type ApiRoute = `${HttpMethod} ${Endpoint}`;
|
|
||||||
|
|
||||||
// CSS properties
|
|
||||||
type CSSUnit = 'px' | 'em' | 'rem' | '%';
|
|
||||||
type Size = `${number}${CSSUnit}`;
|
|
||||||
|
|
||||||
const width: Size = '100px';
|
|
||||||
const height: Size = '50%';
|
|
||||||
```
|
|
||||||
|
|
||||||
### Mapped Types
|
|
||||||
|
|
||||||
```typescript
|
|
||||||
// Make all properties optional recursively
|
|
||||||
type DeepPartial<T> = {
|
|
||||||
[P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
|
|
||||||
};
|
|
||||||
|
|
||||||
// Add prefix to all keys
|
|
||||||
type Prefixed<T, P extends string> = {
|
|
||||||
[K in keyof T as `${P}${Capitalize<string & K>}`]: T[K];
|
|
||||||
};
|
|
||||||
|
|
||||||
type User = { name: string; age: number };
|
|
||||||
type PrefixedUser = Prefixed<User, 'user'>; // { userName: string; userAge: number }
|
|
||||||
|
|
||||||
// Convert to getters
|
|
||||||
type Getters<T> = {
|
|
||||||
[K in keyof T as `get${Capitalize<string & K>}`]: () => T[K];
|
|
||||||
};
|
|
||||||
|
|
||||||
type UserGetters = Getters<User>;
|
|
||||||
// { getName: () => string; getAge: () => number }
|
|
||||||
|
|
||||||
// Remove readonly
|
|
||||||
type Mutable<T> = {
|
|
||||||
-readonly [P in keyof T]: T[P];
|
|
||||||
};
|
|
||||||
|
|
||||||
// Remove optional
|
|
||||||
type Concrete<T> = {
|
|
||||||
[P in keyof T]-?: T[P];
|
|
||||||
};
|
|
||||||
```
|
|
||||||
|
|
||||||
### Conditional Types
|
|
||||||
|
|
||||||
```typescript
|
|
||||||
// Basic conditional
|
|
||||||
type IsString<T> = T extends string ? true : false;
|
|
||||||
|
|
||||||
// Nested conditionals
|
|
||||||
type TypeName<T> =
|
|
||||||
T extends string ? 'string' :
|
|
||||||
T extends number ? 'number' :
|
|
||||||
T extends boolean ? 'boolean' :
|
|
||||||
T extends undefined ? 'undefined' :
|
|
||||||
T extends Function ? 'function' :
|
|
||||||
'object';
|
|
||||||
|
|
||||||
// Distributive conditional types
|
|
||||||
type ToArray<T> = T extends any ? T[] : never;
|
|
||||||
type Result = ToArray<string | number>; // string[] | number[]
|
|
||||||
|
|
||||||
// Infer keyword
|
|
||||||
type Unpacked<T> =
|
|
||||||
T extends Array<infer U> ? U :
|
|
||||||
T extends Promise<infer U> ? U :
|
|
||||||
T;
|
|
||||||
|
|
||||||
type NumberArray = Unpacked<number[]>; // number
|
|
||||||
type StringPromise = Unpacked<Promise<string>>; // string
|
|
||||||
|
|
||||||
// Function return type extraction
|
|
||||||
type ReturnTypeOf<T> = T extends (...args: any[]) => infer R ? R : never;
|
|
||||||
```
|
|
||||||
|
|
||||||
## Type-Safe Patterns
|
|
||||||
|
|
||||||
### Type Guards
|
|
||||||
|
|
||||||
```typescript
|
|
||||||
// Type predicate
|
|
||||||
function isString(value: unknown): value is string {
|
|
||||||
return typeof value === 'string';
|
|
||||||
}
|
|
||||||
|
|
||||||
// Complex type guard
|
|
||||||
interface Cat { meow: () => void; }
|
|
||||||
interface Dog { bark: () => void; }
|
|
||||||
|
|
||||||
function isCat(animal: Cat | Dog): animal is Cat {
|
|
||||||
return 'meow' in animal;
|
|
||||||
}
|
|
||||||
|
|
||||||
function handleAnimal(animal: Cat | Dog) {
|
|
||||||
if (isCat(animal)) {
|
|
||||||
animal.meow(); // TypeScript knows it's a Cat
|
|
||||||
} else {
|
|
||||||
animal.bark(); // TypeScript knows it's a Dog
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
// Array type guard
|
|
||||||
function isStringArray(value: unknown): value is string[] {
|
|
||||||
return Array.isArray(value) && value.every(item => typeof item === 'string');
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Builder Pattern with Types
|
|
||||||
|
|
||||||
```typescript
|
|
||||||
class QueryBuilder<T> {
|
|
||||||
private filters: Array<(item: T) => boolean> = [];
|
|
||||||
private sortFn?: (a: T, b: T) => number;
|
|
||||||
|
|
||||||
where<K extends keyof T>(key: K, value: T[K]): this {
|
|
||||||
this.filters.push(item => item[key] === value);
|
|
||||||
return this;
|
|
||||||
}
|
|
||||||
|
|
||||||
sortBy<K extends keyof T>(key: K, order: 'asc' | 'desc' = 'asc'): this {
|
|
||||||
this.sortFn = (a, b) => {
|
|
||||||
const aVal = a[key];
|
|
||||||
const bVal = b[key];
|
|
||||||
if (aVal < bVal) return order === 'asc' ? -1 : 1;
|
|
||||||
if (aVal > bVal) return order === 'asc' ? 1 : -1;
|
|
||||||
return 0;
|
|
||||||
};
|
|
||||||
return this;
|
|
||||||
}
|
|
||||||
|
|
||||||
execute(data: T[]): T[] {
|
|
||||||
let result = data.filter(item =>
|
|
||||||
this.filters.every(filter => filter(item))
|
|
||||||
);
|
|
||||||
|
|
||||||
if (this.sortFn) {
|
|
||||||
result = result.sort(this.sortFn);
|
|
||||||
}
|
|
||||||
|
|
||||||
return result;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
// Usage
|
|
||||||
const users = [
|
|
||||||
{ name: 'John', age: 30 },
|
|
||||||
{ name: 'Jane', age: 25 },
|
|
||||||
];
|
|
||||||
|
|
||||||
const result = new QueryBuilder<typeof users[0]>()
|
|
||||||
.where('age', 30)
|
|
||||||
.sortBy('name', 'desc')
|
|
||||||
.execute(users);
|
|
||||||
```
|
|
||||||
|
|
||||||
### Type-Safe API Client
|
|
||||||
|
|
||||||
```typescript
|
|
||||||
// Define API schema
|
|
||||||
type ApiSchema = {
|
|
||||||
'/users': {
|
|
||||||
GET: {
|
|
||||||
response: User[];
|
|
||||||
};
|
|
||||||
POST: {
|
|
||||||
body: { name: string; email: string };
|
|
||||||
response: User;
|
|
||||||
};
|
|
||||||
};
|
|
||||||
'/users/:id': {
|
|
||||||
GET: {
|
|
||||||
params: { id: string };
|
|
||||||
response: User;
|
|
||||||
};
|
|
||||||
PATCH: {
|
|
||||||
params: { id: string };
|
|
||||||
body: Partial<User>;
|
|
||||||
response: User;
|
|
||||||
};
|
|
||||||
};
|
|
||||||
};
|
|
||||||
|
|
||||||
// Type-safe client
|
|
||||||
class ApiClient<Schema extends Record<string, any>> {
|
|
||||||
async request<
|
|
||||||
Path extends keyof Schema,
|
|
||||||
Method extends keyof Schema[Path],
|
|
||||||
Config = Schema[Path][Method]
|
|
||||||
>(
|
|
||||||
path: Path,
|
|
||||||
method: Method,
|
|
||||||
options?: {
|
|
||||||
params?: Config extends { params: infer P } ? P : never;
|
|
||||||
body?: Config extends { body: infer B } ? B : never;
|
|
||||||
}
|
|
||||||
): Promise<Config extends { response: infer R } ? R : never> {
|
|
||||||
// Implementation
|
|
||||||
return null as any;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
// Usage (fully type-safe!)
|
|
||||||
const api = new ApiClient<ApiSchema>();
|
|
||||||
|
|
||||||
const users = await api.request('/users', 'GET'); // Type: User[]
|
|
||||||
const user = await api.request('/users/:id', 'GET', {
|
|
||||||
params: { id: '123' }
|
|
||||||
}); // Type: User
|
|
||||||
```
|
|
||||||
|
|
||||||
## TypeScript Configuration
|
## TypeScript Configuration
|
||||||
|
|
||||||
### Strict Configuration
|
**Strict Mode (Required):** Enable strict, strictNullChecks, strictFunctionTypes, noImplicitAny, noImplicitThis, noUnusedLocals, noUnusedParameters, noImplicitReturns, esModuleInterop, skipLibCheck
|
||||||
```json
|
|
||||||
{
|
|
||||||
"compilerOptions": {
|
|
||||||
"target": "ES2022",
|
|
||||||
"lib": ["ES2022", "DOM", "DOM.Iterable"],
|
|
||||||
"module": "ESNext",
|
|
||||||
"moduleResolution": "bundler",
|
|
||||||
"resolveJsonModule": true,
|
|
||||||
|
|
||||||
// Strict mode
|
|
||||||
"strict": true,
|
|
||||||
"strictNullChecks": true,
|
|
||||||
"strictFunctionTypes": true,
|
|
||||||
"strictBindCallApply": true,
|
|
||||||
"strictPropertyInitialization": true,
|
|
||||||
"noImplicitThis": true,
|
|
||||||
"alwaysStrict": true,
|
|
||||||
|
|
||||||
// Additional checks
|
|
||||||
"noUnusedLocals": true,
|
|
||||||
"noUnusedParameters": true,
|
|
||||||
"noImplicitReturns": true,
|
|
||||||
"noFallthroughCasesInSwitch": true,
|
|
||||||
"noUncheckedIndexedAccess": true,
|
|
||||||
|
|
||||||
// Quality of life
|
|
||||||
"esModuleInterop": true,
|
|
||||||
"skipLibCheck": true,
|
|
||||||
"forceConsistentCasingInFileNames": true,
|
|
||||||
|
|
||||||
// Paths
|
|
||||||
"baseUrl": ".",
|
|
||||||
"paths": {
|
|
||||||
"@/*": ["./src/*"]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Migration from JavaScript
|
See `development-guidelines.md` for complete tsconfig.json reference.
|
||||||
|
|
||||||
### Gradual Migration Strategy
|
**Project Organization**
|
||||||
|
- Use path aliases for cleaner imports (`@/components` vs `../../components`)
|
||||||
#### Phase 1: Enable TypeScript
|
- Separate types into dedicated files (`types/`, `@types/`)
|
||||||
```json
|
- Use declaration files (`.d.ts`) for ambient declarations
|
||||||
{
|
- Configure `include` and `exclude` appropriately
|
||||||
"compilerOptions": {
|
|
||||||
"allowJs": true,
|
|
||||||
"checkJs": false,
|
|
||||||
"strict": false
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Phase 2: Add Type Checking
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"compilerOptions": {
|
|
||||||
"allowJs": true,
|
|
||||||
"checkJs": true,
|
|
||||||
"strict": false
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Phase 3: Rename Files
|
|
||||||
Rename `.js` files to `.ts` one at a time, starting with:
|
|
||||||
1. Utility functions
|
|
||||||
2. Constants and types
|
|
||||||
3. Components
|
|
||||||
4. Pages/routes
|
|
||||||
|
|
||||||
#### Phase 4: Enable Strict Mode
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"compilerOptions": {
|
|
||||||
"allowJs": false,
|
|
||||||
"strict": true
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Migration Patterns
|
|
||||||
|
|
||||||
#### From PropTypes to TypeScript
|
|
||||||
```typescript
|
|
||||||
// Before (PropTypes)
|
|
||||||
Component.propTypes = {
|
|
||||||
name: PropTypes.string.isRequired,
|
|
||||||
age: PropTypes.number,
|
|
||||||
onSubmit: PropTypes.func,
|
|
||||||
};
|
|
||||||
|
|
||||||
// After (TypeScript)
|
|
||||||
interface ComponentProps {
|
|
||||||
name: string;
|
|
||||||
age?: number;
|
|
||||||
onSubmit?: () => void;
|
|
||||||
}
|
|
||||||
|
|
||||||
function Component({ name, age, onSubmit }: ComponentProps) {
|
|
||||||
// ...
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Adding Types to Existing Code
|
|
||||||
```typescript
|
|
||||||
// Before (JavaScript)
|
|
||||||
function calculateTotal(items) {
|
|
||||||
return items.reduce((sum, item) => sum + item.price, 0);
|
|
||||||
}
|
|
||||||
|
|
||||||
// After (TypeScript)
|
|
||||||
interface Item {
|
|
||||||
price: number;
|
|
||||||
}
|
|
||||||
|
|
||||||
function calculateTotal(items: Item[]): number {
|
|
||||||
return items.reduce((sum, item) => sum + item.price, 0);
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Performance Optimization
|
|
||||||
|
|
||||||
### Compilation Performance
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"compilerOptions": {
|
|
||||||
"incremental": true,
|
|
||||||
"tsBuildInfoFile": "./.tsbuildinfo"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Type-Only Imports
|
|
||||||
```typescript
|
|
||||||
// Only import types (removed at runtime)
|
|
||||||
import type { User } from './types';
|
|
||||||
|
|
||||||
// Import both value and type
|
|
||||||
import { type User, createUser } from './api';
|
|
||||||
```
|
|
||||||
|
|
||||||
### Skip Library Checks
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"compilerOptions": {
|
|
||||||
"skipLibCheck": true
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Common Patterns & Solutions
|
## Common Patterns & Solutions
|
||||||
|
|
||||||
### Optional Chaining & Nullish Coalescing
|
**Type-Safe API Responses**
|
||||||
```typescript
|
- Define request/response interfaces
|
||||||
const user: User | undefined = getUser();
|
- Use discriminated unions for success/error states
|
||||||
|
- Generic wrapper types for consistent API structure
|
||||||
|
- Zod or similar for runtime validation + type inference
|
||||||
|
|
||||||
// Optional chaining
|
**Type-Safe State Management**
|
||||||
const name = user?.profile?.name;
|
- Discriminated unions for actions (Redux, Zustand)
|
||||||
const firstPost = user?.posts?.[0];
|
- Generic context providers with proper typing
|
||||||
const likeCount = user?.posts?.[0]?.likes?.length;
|
- Type-safe selectors and hooks
|
||||||
|
- Inferred state types from reducers
|
||||||
|
|
||||||
// Nullish coalescing
|
**Form Handling**
|
||||||
const displayName = user?.name ?? 'Anonymous';
|
- Generic form field types
|
||||||
const age = user?.age ?? 0;
|
- Type-safe validation schemas (Zod)
|
||||||
```
|
- Infer form types from schemas
|
||||||
|
- Type-safe error handling
|
||||||
|
|
||||||
### Type Assertions
|
**Database Models**
|
||||||
```typescript
|
- Prisma types for end-to-end type safety
|
||||||
// As assertion
|
- Separate DTOs from database models
|
||||||
const input = document.querySelector('input') as HTMLInputElement;
|
- Use utility types to transform models for APIs
|
||||||
|
- Type-safe query builders
|
||||||
|
|
||||||
// Const assertion
|
## Migration Strategy
|
||||||
const config = {
|
|
||||||
apiUrl: 'https://api.example.com',
|
|
||||||
timeout: 5000,
|
|
||||||
} as const;
|
|
||||||
|
|
||||||
// Non-null assertion (use sparingly!)
|
**From JavaScript to TypeScript**
|
||||||
const value = getValue()!;
|
|
||||||
```
|
|
||||||
|
|
||||||
### Declaration Files
|
1. **Setup** (Day 1)
|
||||||
```typescript
|
- Install TypeScript and types (`@types/*`)
|
||||||
// types.d.ts
|
- Configure `tsconfig.json` with `allowJs: true`
|
||||||
declare module '*.svg' {
|
- Rename one file to `.ts` to verify setup
|
||||||
const content: string;
|
|
||||||
export default content;
|
|
||||||
}
|
|
||||||
|
|
||||||
declare module '*.css' {
|
2. **Gradual Conversion** (Weeks 1-N)
|
||||||
const classes: { [key: string]: string };
|
- Start with utility files (no dependencies)
|
||||||
export default classes;
|
- Move to leaf modules (heavily depended upon)
|
||||||
}
|
- Add types incrementally, use `any` temporarily
|
||||||
|
- Enable strict checks file-by-file
|
||||||
|
|
||||||
// Global types
|
3. **Strict Mode** (Final phase)
|
||||||
declare global {
|
- Enable `noImplicitAny`
|
||||||
interface Window {
|
- Enable `strictNullChecks`
|
||||||
gtag: (...args: any[]) => void;
|
- Enable full `strict` mode
|
||||||
}
|
- Remove `allowJs` when complete
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Let's Improve Your Types
|
**Quick Wins**
|
||||||
|
- Type function parameters and return types
|
||||||
|
- Use utility types instead of manual duplication
|
||||||
|
- Replace enums with const objects + `as const`
|
||||||
|
- Use type guards for runtime type checking
|
||||||
|
|
||||||
Tell me what you need:
|
## Best Practices
|
||||||
- Complex type problems to solve
|
|
||||||
- Code to migrate to TypeScript
|
|
||||||
- Type safety improvements
|
|
||||||
- Generic type implementations
|
|
||||||
- Configuration optimization
|
|
||||||
|
|
||||||
I'll provide:
|
**Do's**
|
||||||
- Precise type definitions
|
- Use `interface` for object shapes (extendable)
|
||||||
- Refactored code with better types
|
- Use `type` for unions, intersections, utilities
|
||||||
- Migration strategies
|
- Prefer `unknown` over `any` for truly unknown types
|
||||||
- Performance improvements
|
- Use `const` assertions for literal types
|
||||||
- Best practices
|
- Leverage type inference (don't over-annotate)
|
||||||
|
- Use generics for reusable, type-safe code
|
||||||
|
- Create utility types for common transformations
|
||||||
|
|
||||||
Let's make your TypeScript codebase rock-solid! 🎯
|
**Don'ts**
|
||||||
|
- Don't use `any` (use `unknown` or proper types)
|
||||||
|
- Don't disable strict checks globally
|
||||||
|
- Don't use `as` casting unless absolutely necessary
|
||||||
|
- Don't ignore TypeScript errors (`@ts-ignore` sparingly)
|
||||||
|
- Don't create overly complex types (keep them readable)
|
||||||
|
- Don't forget to handle null/undefined explicitly
|
||||||
|
|
||||||
|
## Performance & Optimization
|
||||||
|
|
||||||
|
**Compilation Speed**
|
||||||
|
- Use project references for large monorepos
|
||||||
|
- Enable `incremental` compilation
|
||||||
|
- Use `skipLibCheck` to skip checking node_modules types
|
||||||
|
- Exclude unnecessary files (`node_modules`, `dist`)
|
||||||
|
|
||||||
|
**Type Performance**
|
||||||
|
- Avoid deeply nested conditional types
|
||||||
|
- Cache complex type computations
|
||||||
|
- Use simpler types when generics aren't needed
|
||||||
|
- Profile with `tsc --extendedDiagnostics`
|
||||||
|
|
||||||
|
## Debugging Types
|
||||||
|
|
||||||
|
**Inspection Techniques**
|
||||||
|
- Hover in IDE to see inferred types
|
||||||
|
- Use `type X = typeof value` to extract types
|
||||||
|
- Create test types to verify complex types
|
||||||
|
- Use `Parameters<T>` and `ReturnType<T>` to inspect functions
|
||||||
|
|
||||||
|
**Common Issues**
|
||||||
|
- Type too wide: Add constraints or narrow with type guards
|
||||||
|
- Type too narrow: Use union types or generics
|
||||||
|
- Circular references: Break into smaller types
|
||||||
|
- Inference failures: Add explicit type annotations
|
||||||
|
|
||||||
|
When you need TypeScript help, I'll provide precise, practical type solutions that enhance safety without sacrificing developer experience.
|
||||||
|
|
|
||||||
|
|
@ -2,181 +2,129 @@
|
||||||
|
|
||||||
# Architecture Review Checklist
|
# Architecture Review Checklist
|
||||||
|
|
||||||
## Document Completeness
|
## Executive Summary
|
||||||
|
- [ ] System overview (2-3 paragraphs)
|
||||||
|
- [ ] Technology stack with versions
|
||||||
|
- [ ] Architecture pattern (monolith/microservices/serverless/JAMstack)
|
||||||
|
- [ ] 3-5 key design decisions with rationale
|
||||||
|
- [ ] Scalability approach
|
||||||
|
|
||||||
### Executive Summary
|
## Frontend
|
||||||
- [ ] **System Overview** - Clear 2-3 paragraph description of the system
|
- [ ] Framework choice (React/Vue/etc) with version
|
||||||
- [ ] **Technology Stack** - All major technologies listed with versions
|
- [ ] Build tool (Vite/Next.js/Webpack)
|
||||||
- [ ] **Architecture Pattern** - Pattern identified (monolith, microservices, serverless, JAMstack)
|
- [ ] State management strategy
|
||||||
- [ ] **Key Design Decisions** - 3-5 major decisions documented with rationale
|
- [ ] Routing (CSR vs SSR)
|
||||||
- [ ] **Scalability Overview** - High-level scalability approach described
|
- [ ] Styling approach
|
||||||
|
- [ ] Component structure/organization
|
||||||
|
- [ ] Code splitting strategy
|
||||||
|
- [ ] SEO approach (SSR/SSG/CSR)
|
||||||
|
|
||||||
### Frontend Architecture
|
## Backend
|
||||||
- [ ] **Framework Choice** - React, Vue, or other with version and justification
|
- [ ] Node.js version + framework (Express/Fastify/NestJS)
|
||||||
- [ ] **Build Tool** - Vite, Next.js, or Webpack with configuration approach
|
- [ ] API design (REST/GraphQL/tRPC)
|
||||||
- [ ] **State Management** - Clear strategy (React Query, Zustand, Redux, Context)
|
- [ ] Authentication strategy
|
||||||
- [ ] **Routing** - Client-side vs server-side routing explained
|
- [ ] Authorization approach (RBAC/ABAC)
|
||||||
- [ ] **Styling Approach** - CSS solution chosen (Tailwind, CSS Modules, Styled Components)
|
- [ ] Middleware stack
|
||||||
- [ ] **Component Structure** - Folder structure and component organization defined
|
- [ ] Background jobs (if needed)
|
||||||
- [ ] **Code Splitting** - Strategy for bundle optimization
|
- [ ] File upload handling
|
||||||
- [ ] **SEO Strategy** - SSR, SSG, or CSR approach with reasoning
|
- [ ] Email system
|
||||||
|
|
||||||
### Backend Architecture
|
## Database
|
||||||
- [ ] **Runtime and Framework** - Node.js version and framework (Express, Fastify, NestJS)
|
- [ ] Database choice (SQL/NoSQL) with justification
|
||||||
- [ ] **API Design** - REST, GraphQL, or tRPC with endpoint organization
|
- [ ] Schema/entity design
|
||||||
- [ ] **Authentication** - Strategy defined (JWT, OAuth, session-based)
|
- [ ] Key indexes
|
||||||
- [ ] **Authorization** - RBAC, ABAC, or other approach
|
- [ ] Migration strategy
|
||||||
- [ ] **Middleware Stack** - Security, logging, error handling middleware
|
- [ ] Backup & retention
|
||||||
- [ ] **Background Jobs** - Queue system if needed (Bull, BullMQ)
|
- [ ] Connection pooling
|
||||||
- [ ] **File Uploads** - Strategy for handling file uploads
|
|
||||||
- [ ] **Email System** - Email sending approach (SendGrid, SES, SMTP)
|
|
||||||
|
|
||||||
### Database Design
|
## API
|
||||||
- [ ] **Database Choice** - SQL vs NoSQL with justification
|
- [ ] Versioning strategy
|
||||||
- [ ] **Schema Design** - Entity relationships documented
|
- [ ] Request/response format
|
||||||
- [ ] **Indexes** - Key indexes identified for performance
|
- [ ] Error handling format
|
||||||
- [ ] **Migrations** - Migration strategy defined
|
- [ ] Pagination approach
|
||||||
- [ ] **Seeding** - Data seeding approach for development
|
- [ ] Rate limiting
|
||||||
- [ ] **Backup Strategy** - Backup frequency and retention
|
- [ ] CORS configuration
|
||||||
- [ ] **Connection Pooling** - Connection management strategy
|
- [ ] Documentation (OpenAPI/Swagger)
|
||||||
|
|
||||||
### API Design
|
## TypeScript
|
||||||
- [ ] **Versioning Strategy** - URL-based, header-based, or other
|
- [ ] Strict mode configuration
|
||||||
- [ ] **Request/Response Format** - JSON schema or GraphQL schema
|
- [ ] Path aliases
|
||||||
- [ ] **Error Handling** - Standardized error response format
|
- [ ] Shared types location
|
||||||
- [ ] **Pagination** - Cursor-based or offset-based approach
|
|
||||||
- [ ] **Rate Limiting** - Rate limit strategy and thresholds
|
|
||||||
- [ ] **CORS Configuration** - Allowed origins and methods
|
|
||||||
- [ ] **API Documentation** - OpenAPI/Swagger or other documentation
|
|
||||||
|
|
||||||
### TypeScript Configuration
|
## Performance
|
||||||
- [ ] **Strict Mode** - Strict TypeScript settings justified
|
- [ ] Targets (Lighthouse, API latency)
|
||||||
- [ ] **Path Aliases** - Import aliases configured (@/, ~/)
|
- [ ] Caching strategy (Redis/CDN)
|
||||||
- [ ] **Type Definitions** - Strategy for third-party type definitions
|
- [ ] DB query optimization
|
||||||
- [ ] **Shared Types** - Location of shared types between frontend/backend
|
- [ ] Asset optimization
|
||||||
|
- [ ] Bundle size targets
|
||||||
|
|
||||||
## Non-Functional Requirements
|
## Security
|
||||||
|
- [ ] Auth security (token expiry, refresh)
|
||||||
|
- [ ] Authorization checks
|
||||||
|
- [ ] Input validation (frontend + backend)
|
||||||
|
- [ ] SQL injection prevention
|
||||||
|
- [ ] XSS/CSRF protection
|
||||||
|
- [ ] Secrets management
|
||||||
|
- [ ] HTTPS enforcement
|
||||||
|
- [ ] Security headers (Helmet.js)
|
||||||
|
- [ ] Dependency scanning
|
||||||
|
|
||||||
### Performance
|
## Scalability
|
||||||
- [ ] **Performance Targets** - Specific metrics defined (Lighthouse score, API latency)
|
- [ ] Horizontal scaling (stateless design)
|
||||||
- [ ] **Caching Strategy** - Redis, CDN, or in-memory caching approach
|
- [ ] Database scaling strategy
|
||||||
- [ ] **Database Optimization** - Query optimization and indexing plan
|
- [ ] Cache invalidation
|
||||||
- [ ] **Asset Optimization** - Image optimization, lazy loading strategy
|
- [ ] CDN usage
|
||||||
- [ ] **Bundle Size** - Target bundle sizes and code splitting approach
|
- [ ] Auto-scaling triggers
|
||||||
|
|
||||||
### Security
|
## Reliability
|
||||||
- [ ] **Authentication Security** - Token expiration, refresh strategy
|
- [ ] Error handling
|
||||||
- [ ] **Authorization Checks** - Where and how authorization is enforced
|
- [ ] Structured logging
|
||||||
- [ ] **Input Validation** - Validation on both frontend and backend
|
- [ ] Monitoring (APM/error tracking)
|
||||||
- [ ] **SQL Injection Prevention** - Parameterized queries or ORM usage
|
- [ ] Health check endpoints
|
||||||
- [ ] **XSS Prevention** - Content Security Policy and sanitization
|
- [ ] Graceful shutdown
|
||||||
- [ ] **CSRF Protection** - Token-based CSRF protection
|
- [ ] Zero-downtime migrations
|
||||||
- [ ] **Secrets Management** - Environment variables and secret storage
|
- [ ] Rollback plan
|
||||||
- [ ] **HTTPS Enforcement** - SSL/TLS configuration
|
|
||||||
- [ ] **Security Headers** - Helmet.js or equivalent configuration
|
|
||||||
- [ ] **Dependency Scanning** - npm audit or Snyk integration
|
|
||||||
|
|
||||||
### Scalability
|
## DevOps
|
||||||
- [ ] **Horizontal Scaling** - Stateless application design
|
- [ ] CI/CD pipeline
|
||||||
- [ ] **Database Scaling** - Read replicas or sharding strategy
|
- [ ] Environment strategy (dev/staging/prod)
|
||||||
- [ ] **Caching Layer** - Cache invalidation strategy
|
- [ ] Infrastructure as code
|
||||||
- [ ] **CDN Usage** - Static asset delivery via CDN
|
- [ ] Container strategy
|
||||||
- [ ] **Load Balancing** - Load balancer configuration if needed
|
- [ ] Deployment strategy (blue-green/canary/rolling)
|
||||||
- [ ] **Auto-scaling** - Metrics and triggers for scaling
|
- [ ] Backup & disaster recovery (RTO/RPO)
|
||||||
|
|
||||||
### Reliability
|
## Development & Quality
|
||||||
- [ ] **Error Handling** - Global error handling strategy
|
- [ ] README with setup instructions
|
||||||
- [ ] **Logging Strategy** - Structured logging with correlation IDs
|
- [ ] .env.example with all variables
|
||||||
- [ ] **Monitoring** - APM and error tracking tools (Sentry, Datadog)
|
- [ ] ESLint + Prettier configured
|
||||||
- [ ] **Health Checks** - Liveness and readiness endpoints
|
- [ ] Pre-commit hooks (Husky)
|
||||||
- [ ] **Graceful Shutdown** - Proper cleanup on application shutdown
|
- [ ] Code style guide documented
|
||||||
- [ ] **Database Migrations** - Zero-downtime migration strategy
|
|
||||||
- [ ] **Rollback Plan** - How to rollback failed deployments
|
|
||||||
|
|
||||||
### DevOps & Deployment
|
## Testing
|
||||||
- [ ] **CI/CD Pipeline** - Build, test, and deploy automation
|
- [ ] Unit test framework (Jest/Vitest)
|
||||||
- [ ] **Environment Strategy** - Development, staging, production environments
|
- [ ] Integration tests (Supertest)
|
||||||
- [ ] **Infrastructure as Code** - Terraform, CloudFormation, or Docker Compose
|
- [ ] E2E tests (Playwright/Cypress)
|
||||||
- [ ] **Container Strategy** - Docker configuration and orchestration
|
- [ ] Coverage goals (>80%)
|
||||||
- [ ] **Deployment Strategy** - Blue-green, canary, or rolling deployments
|
- [ ] Tests in CI pipeline
|
||||||
- [ ] **Backup and Disaster Recovery** - RTO and RPO defined
|
|
||||||
|
|
||||||
## Implementation Readiness
|
## Documentation
|
||||||
|
- [ ] Architecture diagrams
|
||||||
### Development Environment
|
- [ ] Database schema (ER diagram)
|
||||||
- [ ] **Local Setup** - Clear README with setup instructions
|
- [ ] API documentation (OpenAPI/GraphQL)
|
||||||
- [ ] **Environment Variables** - .env.example file with all required variables
|
- [ ] Deployment guide
|
||||||
- [ ] **Database Setup** - Local database setup instructions
|
- [ ] ADRs for key decisions
|
||||||
- [ ] **Seed Data** - Development seed data available
|
|
||||||
- [ ] **Hot Reload** - Development server with hot module replacement
|
|
||||||
|
|
||||||
### Code Quality
|
|
||||||
- [ ] **Linting** - ESLint configuration defined
|
|
||||||
- [ ] **Formatting** - Prettier configuration
|
|
||||||
- [ ] **Pre-commit Hooks** - Husky or lint-staged configuration
|
|
||||||
- [ ] **Code Style Guide** - Naming conventions and patterns documented
|
|
||||||
- [ ] **TypeScript Standards** - Type usage guidelines
|
|
||||||
|
|
||||||
### Testing Strategy
|
|
||||||
- [ ] **Unit Testing** - Framework chosen (Jest, Vitest)
|
|
||||||
- [ ] **Integration Testing** - API testing approach (Supertest)
|
|
||||||
- [ ] **E2E Testing** - E2E framework (Playwright, Cypress)
|
|
||||||
- [ ] **Coverage Goals** - Target code coverage percentages
|
|
||||||
- [ ] **CI Integration** - Tests run in CI pipeline
|
|
||||||
|
|
||||||
### Documentation
|
|
||||||
- [ ] **Architecture Diagrams** - System architecture visualized
|
|
||||||
- [ ] **Database Schema** - ER diagram or schema documentation
|
|
||||||
- [ ] **API Documentation** - Endpoint documentation (Swagger, GraphQL introspection)
|
|
||||||
- [ ] **Deployment Guide** - How to deploy to production
|
|
||||||
- [ ] **ADRs** - Architecture Decision Records for key choices
|
|
||||||
|
|
||||||
## Risk Assessment
|
## Risk Assessment
|
||||||
|
- [ ] Complexity risks identified
|
||||||
|
- [ ] Performance bottlenecks documented
|
||||||
|
- [ ] Scalability limits understood
|
||||||
|
- [ ] Technology risks flagged
|
||||||
|
- [ ] Mitigation plans for each risk
|
||||||
|
|
||||||
### Technical Risks
|
## Validation
|
||||||
- [ ] **Complexity Risks** - Over-engineering or under-engineering identified
|
- [ ] Requirements coverage complete
|
||||||
- [ ] **Performance Bottlenecks** - Potential bottlenecks documented
|
- [ ] Team has necessary skills
|
||||||
- [ ] **Scalability Limits** - Known scalability constraints
|
- [ ] Infrastructure costs estimated
|
||||||
- [ ] **Technology Risks** - Unproven or bleeding-edge tech flagged
|
- [ ] Architecture matches scope (not over/under-engineered)
|
||||||
- [ ] **Dependency Risks** - Critical third-party dependencies assessed
|
|
||||||
|
|
||||||
### Mitigation Strategies
|
**Ready for Implementation:** [ ] Yes [ ] No
|
||||||
- [ ] **Risk Mitigation** - Plan for each identified risk
|
|
||||||
- [ ] **Fallback Options** - Alternative approaches documented
|
|
||||||
- [ ] **Monitoring Plan** - How risks will be monitored in production
|
|
||||||
|
|
||||||
## Validation Questions
|
|
||||||
|
|
||||||
### Alignment with Requirements
|
|
||||||
- [ ] **Requirements Coverage** - All functional requirements addressed
|
|
||||||
- [ ] **Non-functional Requirements** - Performance, security, scalability covered
|
|
||||||
- [ ] **Scope Appropriateness** - Architecture matches project scope
|
|
||||||
- [ ] **Over-engineering Check** - Not adding unnecessary complexity
|
|
||||||
- [ ] **Future-proofing** - Extensible without being over-architected
|
|
||||||
|
|
||||||
### Team Capability
|
|
||||||
- [ ] **Team Skills** - Team has or can acquire necessary skills
|
|
||||||
- [ ] **Learning Curve** - New technologies have acceptable learning curve
|
|
||||||
- [ ] **Support Resources** - Documentation and community support available
|
|
||||||
- [ ] **Maintenance Burden** - Architecture is maintainable long-term
|
|
||||||
|
|
||||||
### Cost Considerations
|
|
||||||
- [ ] **Infrastructure Costs** - Estimated monthly costs
|
|
||||||
- [ ] **Development Costs** - Time and effort realistic
|
|
||||||
- [ ] **Third-party Services** - External service costs budgeted
|
|
||||||
- [ ] **Scaling Costs** - Cost implications of scaling understood
|
|
||||||
|
|
||||||
## Final Assessment
|
|
||||||
|
|
||||||
**Architecture Quality Rating:** ⭐⭐⭐⭐⭐
|
|
||||||
|
|
||||||
**Ready for Implementation:** [ ] Yes [ ] No
|
|
||||||
|
|
||||||
**Critical Issues to Address:**
|
|
||||||
_List any must-fix issues before development begins_
|
|
||||||
|
|
||||||
**Recommendations:**
|
|
||||||
_Suggestions for improvement or alternative approaches_
|
|
||||||
|
|
||||||
**Next Steps:**
|
|
||||||
_What needs to happen before story creation begins_
|
|
||||||
|
|
@ -2,305 +2,67 @@
|
||||||
|
|
||||||
# Deployment Strategies for JavaScript Applications
|
# Deployment Strategies for JavaScript Applications
|
||||||
|
|
||||||
|
Quick reference for deployment patterns and platforms.
|
||||||
|
|
||||||
## Deployment Patterns
|
## Deployment Patterns
|
||||||
|
|
||||||
### 1. Rolling Deployment
|
**Rolling Deployment** - Gradual instance replacement. Pros: Simple, zero downtime. Cons: Old/new versions mix during deploy. Best for: Most apps (default)
|
||||||
**How it works:** Gradually replace old instances with new ones
|
|
||||||
|
|
||||||
**Pros:**
|
**Blue-Green** - Two identical environments, switch traffic. Pros: Instant rollback, pre-test. Cons: 2x infrastructure cost. Best for: Critical apps needing instant rollback
|
||||||
- Simple to implement
|
|
||||||
- No additional infrastructure needed
|
|
||||||
- Zero downtime
|
|
||||||
|
|
||||||
**Cons:**
|
**Canary** - Route small % to new version, increase gradually. Pros: Safe real-user testing, early detection. Cons: Complex routing, needs good monitoring. Best for: High-risk changes, large user bases
|
||||||
- During deployment, old and new versions run simultaneously
|
|
||||||
- Rollback requires another deployment
|
|
||||||
|
|
||||||
**Best for:** Most applications, default choice
|
## Recommended Platforms
|
||||||
|
|
||||||
### 2. Blue-Green Deployment
|
### Frontend (Next.js/React)
|
||||||
**How it works:** Two identical environments, switch traffic between them
|
**Vercel** - Zero-config Next.js, automatic HTTPS, global CDN, preview deployments, serverless functions
|
||||||
|
**Netlify** - JAMstack focus, forms, serverless, similar to Vercel
|
||||||
|
|
||||||
**Pros:**
|
### Backend / Full-Stack
|
||||||
- Instant rollback (switch back)
|
**Railway** - Simple, PostgreSQL/Redis/MongoDB included, GitHub integration, automatic SSL
|
||||||
- Test new version before switching
|
**Render** - Similar to Railway, good for Node.js/Docker, managed databases
|
||||||
- Zero downtime
|
**Fly.io** - Global edge deployment, Docker-based, great for WebSocket apps
|
||||||
|
|
||||||
**Cons:**
|
### Enterprise / Complex
|
||||||
- Double infrastructure cost during deployment
|
**AWS (ECS/Fargate)** - Full control, scalable, complex setup, higher cost
|
||||||
- Database migrations can be tricky
|
**Google Cloud Run** - Serverless containers, auto-scaling, pay per use
|
||||||
|
**DigitalOcean App Platform** - Simple Heroku alternative, reasonable pricing
|
||||||
|
|
||||||
**Best for:** Critical applications needing instant rollback
|
## CI/CD Pattern
|
||||||
|
|
||||||
### 3. Canary Deployment
|
**GitHub Actions** - Test on PR, deploy on merge to main
|
||||||
**How it works:** Route small % of traffic to new version, gradually increase
|
**GitLab CI** - Similar workflow, built-in container registry
|
||||||
|
**CircleCI** - Fast, good caching, pipeline visualization
|
||||||
|
|
||||||
**Pros:**
|
**Standard Flow:**
|
||||||
- Test with real users safely
|
1. Push to branch → Run tests
|
||||||
- Early problem detection
|
2. Merge to main → Build + test
|
||||||
- Gradual rollout reduces risk
|
3. Deploy to staging → Run smoke tests
|
||||||
|
4. Deploy to production (manual approval for critical apps)
|
||||||
**Cons:**
|
5. Monitor metrics post-deploy
|
||||||
- Complex routing logic
|
|
||||||
- Need good monitoring
|
|
||||||
- Longer deployment time
|
|
||||||
|
|
||||||
**Best for:** High-risk changes, large user bases
|
|
||||||
|
|
||||||
## Platform-Specific Deployment
|
|
||||||
|
|
||||||
### Vercel (Recommended for Next.js)
|
|
||||||
```bash
|
|
||||||
# Install Vercel CLI
|
|
||||||
npm i -g vercel
|
|
||||||
|
|
||||||
# Deploy
|
|
||||||
vercel --prod
|
|
||||||
|
|
||||||
# Environment variables
|
|
||||||
vercel env add DATABASE_URL production
|
|
||||||
```
|
|
||||||
|
|
||||||
**Features:**
|
|
||||||
- Automatic HTTPS
|
|
||||||
- Global CDN
|
|
||||||
- Preview deployments for PRs
|
|
||||||
- Zero-config for Next.js
|
|
||||||
- Serverless functions
|
|
||||||
|
|
||||||
### Railway (Backend/Full-stack)
|
|
||||||
```bash
|
|
||||||
# Install Railway CLI
|
|
||||||
npm i -g @railway/cli
|
|
||||||
|
|
||||||
# Login and init
|
|
||||||
railway login
|
|
||||||
railway init
|
|
||||||
|
|
||||||
# Deploy
|
|
||||||
railway up
|
|
||||||
```
|
|
||||||
|
|
||||||
**Features:**
|
|
||||||
- PostgreSQL, Redis, MongoDB
|
|
||||||
- Environment variables
|
|
||||||
- Automatic SSL
|
|
||||||
- GitHub integration
|
|
||||||
|
|
||||||
### Docker + Fly.io
|
|
||||||
```dockerfile
|
|
||||||
# Dockerfile
|
|
||||||
FROM node:18-alpine
|
|
||||||
WORKDIR /app
|
|
||||||
COPY package*.json ./
|
|
||||||
RUN npm ci --only=production
|
|
||||||
COPY . .
|
|
||||||
RUN npm run build
|
|
||||||
CMD ["npm", "start"]
|
|
||||||
```
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Deploy
|
|
||||||
fly launch
|
|
||||||
fly deploy
|
|
||||||
```
|
|
||||||
|
|
||||||
### AWS (EC2/ECS/Fargate)
|
|
||||||
- Most flexible
|
|
||||||
- Complex setup
|
|
||||||
- Full control
|
|
||||||
- Higher costs
|
|
||||||
|
|
||||||
### DigitalOcean App Platform
|
|
||||||
- Simple like Heroku
|
|
||||||
- Reasonable pricing
|
|
||||||
- Good for full-stack apps
|
|
||||||
|
|
||||||
## CI/CD Setup
|
|
||||||
|
|
||||||
### GitHub Actions
|
|
||||||
**.github/workflows/deploy.yml:**
|
|
||||||
```yaml
|
|
||||||
name: Deploy to Production
|
|
||||||
|
|
||||||
on:
|
|
||||||
push:
|
|
||||||
branches: [main]
|
|
||||||
|
|
||||||
jobs:
|
|
||||||
test:
|
|
||||||
runs-on: ubuntu-latest
|
|
||||||
steps:
|
|
||||||
- uses: actions/checkout@v3
|
|
||||||
- uses: actions/setup-node@v3
|
|
||||||
with:
|
|
||||||
node-version: 18
|
|
||||||
- run: npm ci
|
|
||||||
- run: npm test
|
|
||||||
- run: npm run build
|
|
||||||
|
|
||||||
deploy:
|
|
||||||
needs: test
|
|
||||||
runs-on: ubuntu-latest
|
|
||||||
steps:
|
|
||||||
- uses: actions/checkout@v3
|
|
||||||
- name: Deploy to Vercel
|
|
||||||
run: npx vercel --prod --token=${{ secrets.VERCEL_TOKEN }}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Database Migrations
|
|
||||||
|
|
||||||
### Strategy 1: Migrations Before Deployment
|
|
||||||
```bash
|
|
||||||
# Run migrations before deploying new code
|
|
||||||
npm run db:migrate
|
|
||||||
npm run deploy
|
|
||||||
```
|
|
||||||
|
|
||||||
**Pros:** Safer, new code expects new schema
|
|
||||||
|
|
||||||
**Cons:** Brief downtime if migration is slow
|
|
||||||
|
|
||||||
### Strategy 2: Backward-Compatible Migrations
|
|
||||||
```bash
|
|
||||||
# 1. Deploy code that works with old and new schema
|
|
||||||
# 2. Run migration
|
|
||||||
# 3. Deploy code that uses new schema only
|
|
||||||
```
|
|
||||||
|
|
||||||
**Pros:** Zero downtime
|
|
||||||
|
|
||||||
**Cons:** More complex, requires multiple deploys
|
|
||||||
|
|
||||||
### Prisma Migrations
|
|
||||||
```bash
|
|
||||||
# Generate migration
|
|
||||||
npx prisma migrate dev --name add_user_role
|
|
||||||
|
|
||||||
# Apply in production
|
|
||||||
npx prisma migrate deploy
|
|
||||||
```
|
|
||||||
|
|
||||||
## Environment Management
|
## Environment Management
|
||||||
|
|
||||||
### Environments
|
**Local:** .env file (never commit)
|
||||||
- **Development:** Local machine
|
**Staging/Production:** Platform environment variables or secrets manager
|
||||||
- **Staging:** Pre-production testing
|
**Secrets:** AWS Secrets Manager, HashiCorp Vault, or platform-specific
|
||||||
- **Production:** Live application
|
|
||||||
|
|
||||||
### Environment Variables
|
## Database Migrations
|
||||||
```bash
|
|
||||||
# Development (.env.local)
|
|
||||||
DATABASE_URL=postgresql://localhost:5432/dev
|
|
||||||
NEXT_PUBLIC_API_URL=http://localhost:3000
|
|
||||||
|
|
||||||
# Staging
|
**Strategy:** Run migrations BEFORE deploying new code
|
||||||
DATABASE_URL=postgresql://staging.db/app
|
**Tools:** Prisma migrate, TypeORM migrations, or raw SQL scripts
|
||||||
NEXT_PUBLIC_API_URL=https://staging.app.com
|
**Safety:** Test migrations on staging first, backup before production
|
||||||
|
|
||||||
# Production
|
## Monitoring Post-Deploy
|
||||||
DATABASE_URL=postgresql://prod.db/app
|
|
||||||
NEXT_PUBLIC_API_URL=https://app.com
|
|
||||||
```
|
|
||||||
|
|
||||||
## Rollback Strategies
|
- Health check endpoints (`/health`, `/ready`)
|
||||||
|
- Error tracking (Sentry, Rollbar)
|
||||||
|
- Performance monitoring (Datadog, New Relic)
|
||||||
|
- Log aggregation (Logtail, Better Stack)
|
||||||
|
- Alert on error rate spikes or response time degradation
|
||||||
|
|
||||||
### 1. Git Revert + Redeploy
|
## Rollback Plan
|
||||||
```bash
|
|
||||||
git revert HEAD
|
|
||||||
git push origin main
|
|
||||||
# Triggers new deployment
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2. Previous Build Rollback
|
**Immediate:** Revert to previous deployment (platform UI or CLI)
|
||||||
Most platforms keep previous builds:
|
**Database:** Keep backward-compatible migrations for at least one version
|
||||||
```bash
|
**Feature Flags:** Use feature flags to disable new features without redeployment
|
||||||
# Vercel
|
|
||||||
vercel rollback
|
|
||||||
|
|
||||||
# Railway
|
|
||||||
railway rollback
|
|
||||||
|
|
||||||
# Fly.io
|
|
||||||
fly releases
|
|
||||||
fly deploy --image <previous-image>
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3. Blue-Green Switch Back
|
|
||||||
If using blue-green, switch traffic back to previous environment
|
|
||||||
|
|
||||||
## Health Checks
|
|
||||||
|
|
||||||
```typescript
|
|
||||||
// /api/health endpoint
|
|
||||||
app.get('/health', async (req, res) => {
|
|
||||||
try {
|
|
||||||
// Check database
|
|
||||||
await prisma.$queryRaw`SELECT 1`;
|
|
||||||
|
|
||||||
// Check Redis
|
|
||||||
await redis.ping();
|
|
||||||
|
|
||||||
res.json({ status: 'healthy' });
|
|
||||||
} catch (error) {
|
|
||||||
res.status(503).json({ status: 'unhealthy', error });
|
|
||||||
}
|
|
||||||
});
|
|
||||||
```
|
|
||||||
|
|
||||||
## Monitoring Post-Deployment
|
|
||||||
|
|
||||||
### Metrics to Watch
|
|
||||||
- Error rate
|
|
||||||
- Response time (p50, p95, p99)
|
|
||||||
- CPU/Memory usage
|
|
||||||
- Database connection pool
|
|
||||||
- API endpoint latencies
|
|
||||||
|
|
||||||
### Tools
|
|
||||||
- **Sentry:** Error tracking
|
|
||||||
- **Datadog:** Full APM
|
|
||||||
- **Vercel Analytics:** Frontend vitals
|
|
||||||
- **PostHog:** Product analytics
|
|
||||||
- **Uptime Robot:** Uptime monitoring
|
|
||||||
|
|
||||||
## Deployment Checklist
|
|
||||||
|
|
||||||
### Pre-Deployment
|
|
||||||
- [ ] All tests pass locally and in CI
|
|
||||||
- [ ] Code reviewed and approved
|
|
||||||
- [ ] Database migrations tested on staging
|
|
||||||
- [ ] Environment variables configured
|
|
||||||
- [ ] Rollback plan ready
|
|
||||||
- [ ] Team notified of deployment
|
|
||||||
|
|
||||||
### During Deployment
|
|
||||||
- [ ] Monitor error rates
|
|
||||||
- [ ] Check health endpoints
|
|
||||||
- [ ] Verify critical user flows
|
|
||||||
- [ ] Watch application metrics
|
|
||||||
|
|
||||||
### Post-Deployment
|
|
||||||
- [ ] Smoke test production
|
|
||||||
- [ ] Check error tracking (Sentry)
|
|
||||||
- [ ] Monitor for 24 hours
|
|
||||||
- [ ] Update changelog
|
|
||||||
- [ ] Mark deployment as successful
|
|
||||||
|
|
||||||
## Common Issues & Solutions
|
|
||||||
|
|
||||||
**Issue:** Database connection pool exhausted
|
|
||||||
|
|
||||||
**Solution:** Increase pool size or implement connection pooling middleware
|
|
||||||
|
|
||||||
**Issue:** Cold starts in serverless
|
|
||||||
|
|
||||||
**Solution:** Use provisioned concurrency or switch to container-based hosting
|
|
||||||
|
|
||||||
**Issue:** Build failing in CI
|
|
||||||
|
|
||||||
**Solution:** Ensure all dependencies in package.json, check environment variables
|
|
||||||
|
|
||||||
**Issue:** Rollback needed
|
|
||||||
|
|
||||||
**Solution:** Use platform-specific rollback or git revert + redeploy
|
|
||||||
|
|
|
||||||
|
|
@ -2,354 +2,67 @@
|
||||||
|
|
||||||
# JavaScript/TypeScript Development Guidelines
|
# JavaScript/TypeScript Development Guidelines
|
||||||
|
|
||||||
## Overview
|
Quick reference for coding standards and conventions. See `best-practices.md` for implementation patterns.
|
||||||
This document establishes coding standards, best practices, and conventions for JavaScript/TypeScript full-stack development. These guidelines ensure consistency, quality, and maintainability.
|
|
||||||
|
|
||||||
## TypeScript Standards
|
## TypeScript Standards
|
||||||
|
|
||||||
### Configuration
|
**Required tsconfig.json**: strict: true, noImplicitAny, strictNullChecks, noImplicitReturns, noUnusedLocals
|
||||||
**Required tsconfig.json settings:**
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"compilerOptions": {
|
|
||||||
"strict": true,
|
|
||||||
"noImplicitAny": true,
|
|
||||||
"strictNullChecks": true,
|
|
||||||
"strictFunctionTypes": true,
|
|
||||||
"noImplicitReturns": true,
|
|
||||||
"noUnusedLocals": true,
|
|
||||||
"noUnusedParameters": true,
|
|
||||||
"esModuleInterop": true,
|
|
||||||
"skipLibCheck": true,
|
|
||||||
"forceConsistentCasingInFileNames": true
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Type Definitions
|
**Type Rules:**
|
||||||
- **No `any` types** - Use `unknown` if type is truly unknown
|
- No `any` - use `unknown` for truly unknown types
|
||||||
- **Interface vs Type** - Prefer interfaces for object shapes, types for unions/intersections
|
- `interface` for objects, `type` for unions/intersections
|
||||||
- **Explicit return types** - Always specify return types for functions
|
- Explicit function return types
|
||||||
- **Proper generics** - Use generics for reusable type-safe code
|
- Generics for reusable type-safe code
|
||||||
|
|
||||||
```typescript
|
|
||||||
// ✅ Good
|
|
||||||
interface UserProps {
|
|
||||||
id: string;
|
|
||||||
name: string;
|
|
||||||
email: string;
|
|
||||||
}
|
|
||||||
|
|
||||||
function getUser(id: string): Promise<User | null> {
|
|
||||||
return db.user.findUnique({ where: { id } });
|
|
||||||
}
|
|
||||||
|
|
||||||
// ❌ Bad
|
|
||||||
function getUser(id: any): any {
|
|
||||||
return db.user.findUnique({ where: { id } });
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Naming Conventions
|
## Naming Conventions
|
||||||
|
|
||||||
### Files and Folders
|
**Files:** kebab-case (utils), PascalCase (components), camelCase (hooks)
|
||||||
- **kebab-case** for utility files: `api-client.ts`, `string-utils.ts`
|
**Variables:** camelCase (functions/vars), PascalCase (classes), UPPER_SNAKE_CASE (constants)
|
||||||
- **PascalCase** for components: `UserProfile.tsx`, `TodoList.tsx`
|
**Descriptive:** `isLoading` not `loading`, `handleSubmit` not `submit`
|
||||||
- **camelCase** for hooks: `useAuth.ts`, `useLocalStorage.ts`
|
|
||||||
|
|
||||||
### Variables and Functions
|
## React Guidelines
|
||||||
- **camelCase** for variables and functions: `userName`, `fetchData()`
|
|
||||||
- **PascalCase** for classes and components: `UserService`, `Button`
|
|
||||||
- **UPPER_SNAKE_CASE** for constants: `API_BASE_URL`, `MAX_RETRIES`
|
|
||||||
- **Descriptive names** - `isLoading` not `loading`, `handleSubmit` not `submit`
|
|
||||||
|
|
||||||
```typescript
|
**Hooks:** Top-level only, consistent order, no conditional calls
|
||||||
// ✅ Good
|
**State:** useState (local), React Query (server), Zustand (global), useMemo (derived)
|
||||||
const MAX_RETRY_COUNT = 3;
|
**Components:** < 300 lines, TypeScript props, functional with hooks
|
||||||
const isAuthenticated = checkAuth();
|
|
||||||
function calculateTotalPrice(items: Item[]): number { }
|
|
||||||
|
|
||||||
// ❌ Bad
|
## Backend Guidelines
|
||||||
const max = 3;
|
|
||||||
const auth = checkAuth();
|
|
||||||
function calc(items: any): any { }
|
|
||||||
```
|
|
||||||
|
|
||||||
## React Best Practices
|
**API Design:** RESTful (`GET /api/v1/users` not `/getUsers`), versioning, proper HTTP methods/codes
|
||||||
|
**Validation:** Zod or Joi for all inputs, sanitize outputs
|
||||||
|
**Error Handling:** Custom error classes, centralized middleware, structured logging
|
||||||
|
|
||||||
### Component Structure
|
## Project Structure
|
||||||
```typescript
|
|
||||||
// ✅ Good component structure
|
|
||||||
interface ButtonProps {
|
|
||||||
children: React.ReactNode;
|
|
||||||
onClick: () => void;
|
|
||||||
variant?: 'primary' | 'secondary';
|
|
||||||
disabled?: boolean;
|
|
||||||
}
|
|
||||||
|
|
||||||
export function Button({
|
**Frontend:** components/ (ui, features, layout), hooks/, lib/, pages/, styles/, types/
|
||||||
children,
|
**Backend:** controllers/, services/, repositories/, middleware/, routes/, types/, config/
|
||||||
onClick,
|
|
||||||
variant = 'primary',
|
|
||||||
disabled = false
|
|
||||||
}: ButtonProps) {
|
|
||||||
return (
|
|
||||||
<button
|
|
||||||
onClick={onClick}
|
|
||||||
disabled={disabled}
|
|
||||||
className={`btn btn-${variant}`}
|
|
||||||
>
|
|
||||||
{children}
|
|
||||||
</button>
|
|
||||||
);
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Hooks Rules
|
|
||||||
- Call hooks at the top level
|
|
||||||
- Call hooks in the same order
|
|
||||||
- Only call hooks from React functions
|
|
||||||
|
|
||||||
```typescript
|
|
||||||
// ✅ Good
|
|
||||||
function Component() {
|
|
||||||
const [state, setState] = useState(0);
|
|
||||||
const data = useFetch('/api/data');
|
|
||||||
|
|
||||||
useEffect(() => {
|
|
||||||
// effect
|
|
||||||
}, []);
|
|
||||||
|
|
||||||
return <div>{data}</div>;
|
|
||||||
}
|
|
||||||
|
|
||||||
// ❌ Bad - conditional hook
|
|
||||||
function Component() {
|
|
||||||
if (condition) {
|
|
||||||
useState(0); // ❌ Don't do this
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### State Management
|
|
||||||
- **Local state** - `useState` for component-only state
|
|
||||||
- **Server state** - React Query/SWR for API data
|
|
||||||
- **Global state** - Zustand/Redux only when necessary
|
|
||||||
- **Derived state** - `useMemo` for computed values
|
|
||||||
|
|
||||||
## Backend Best Practices
|
|
||||||
|
|
||||||
### API Endpoints
|
|
||||||
```typescript
|
|
||||||
// ✅ Good - RESTful design
|
|
||||||
GET /api/v1/users
|
|
||||||
POST /api/v1/users
|
|
||||||
PATCH /api/v1/users/:id
|
|
||||||
DELETE /api/v1/users/:id
|
|
||||||
|
|
||||||
// ❌ Bad - non-RESTful
|
|
||||||
GET /api/v1/getUsers
|
|
||||||
POST /api/v1/createUser
|
|
||||||
POST /api/v1/updateUser/:id
|
|
||||||
```
|
|
||||||
|
|
||||||
### Error Handling
|
|
||||||
```typescript
|
|
||||||
// ✅ Good - centralized error handling
|
|
||||||
class AppError extends Error {
|
|
||||||
constructor(
|
|
||||||
public statusCode: number,
|
|
||||||
public message: string,
|
|
||||||
public isOperational = true
|
|
||||||
) {
|
|
||||||
super(message);
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
app.use((err: Error, req: Request, res: Response, next: NextFunction) => {
|
|
||||||
if (err instanceof AppError) {
|
|
||||||
return res.status(err.statusCode).json({
|
|
||||||
error: err.message
|
|
||||||
});
|
|
||||||
}
|
|
||||||
|
|
||||||
console.error(err);
|
|
||||||
res.status(500).json({ error: 'Internal server error' });
|
|
||||||
});
|
|
||||||
```
|
|
||||||
|
|
||||||
### Input Validation
|
|
||||||
```typescript
|
|
||||||
// ✅ Good - Zod validation
|
|
||||||
import { z } from 'zod';
|
|
||||||
|
|
||||||
const createUserSchema = z.object({
|
|
||||||
email: z.string().email(),
|
|
||||||
name: z.string().min(2),
|
|
||||||
password: z.string().min(8),
|
|
||||||
});
|
|
||||||
|
|
||||||
app.post('/users', async (req, res) => {
|
|
||||||
const result = createUserSchema.safeParse(req.body);
|
|
||||||
|
|
||||||
if (!result.success) {
|
|
||||||
return res.status(400).json({
|
|
||||||
errors: result.error.errors
|
|
||||||
});
|
|
||||||
}
|
|
||||||
|
|
||||||
const user = await createUser(result.data);
|
|
||||||
res.status(201).json(user);
|
|
||||||
});
|
|
||||||
```
|
|
||||||
|
|
||||||
## Code Organization
|
|
||||||
|
|
||||||
### Frontend Structure
|
|
||||||
```
|
|
||||||
src/
|
|
||||||
├── components/
|
|
||||||
│ ├── ui/ # Reusable UI components
|
|
||||||
│ ├── features/ # Feature-specific components
|
|
||||||
│ └── layout/ # Layout components
|
|
||||||
├── hooks/ # Custom React hooks
|
|
||||||
├── lib/ # Utilities and helpers
|
|
||||||
├── pages/ # Next.js pages or routes
|
|
||||||
├── styles/ # Global styles
|
|
||||||
├── types/ # TypeScript types
|
|
||||||
└── utils/ # Utility functions
|
|
||||||
```
|
|
||||||
|
|
||||||
### Backend Structure
|
|
||||||
```
|
|
||||||
src/
|
|
||||||
├── controllers/ # Request handlers
|
|
||||||
├── services/ # Business logic
|
|
||||||
├── repositories/ # Data access layer
|
|
||||||
├── middleware/ # Express/Fastify middleware
|
|
||||||
├── routes/ # Route definitions
|
|
||||||
├── types/ # TypeScript types
|
|
||||||
├── utils/ # Utility functions
|
|
||||||
└── config/ # Configuration files
|
|
||||||
```
|
|
||||||
|
|
||||||
## Testing Standards
|
## Testing Standards
|
||||||
|
|
||||||
### Frontend Tests
|
**Frontend:** React Testing Library, test interactions not implementation, >80% coverage
|
||||||
```typescript
|
**Backend:** Jest + Supertest, integration tests for APIs, mock external services, >85% coverage
|
||||||
// ✅ Good - React Testing Library
|
|
||||||
import { render, screen, fireEvent } from '@testing-library/react';
|
|
||||||
import { Button } from './Button';
|
|
||||||
|
|
||||||
describe('Button', () => {
|
## Security (see security-guidelines.md for details)
|
||||||
it('calls onClick when clicked', async () => {
|
|
||||||
const handleClick = jest.fn();
|
|
||||||
render(<Button onClick={handleClick}>Click me</Button>);
|
|
||||||
|
|
||||||
await fireEvent.click(screen.getByText('Click me'));
|
**Auth:** bcrypt for passwords, JWT (short expiry), refresh tokens, httpOnly cookies
|
||||||
|
**Input:** Validate ALL inputs (Zod/Joi), sanitize HTML, parameterized queries
|
||||||
|
**API:** CORS (specific origins), rate limiting, CSRF protection, Helmet.js headers
|
||||||
|
|
||||||
expect(handleClick).toHaveBeenCalledTimes(1);
|
## Performance (see best-practices.md for implementation)
|
||||||
});
|
|
||||||
});
|
|
||||||
```
|
|
||||||
|
|
||||||
### Backend Tests
|
**Frontend:** Code splitting, lazy loading, next/image, memoization, virtual scrolling
|
||||||
```typescript
|
**Backend:** Database indexes, connection pooling, Redis caching, pagination, background jobs
|
||||||
// ✅ Good - Supertest API tests
|
|
||||||
import request from 'supertest';
|
|
||||||
import { app } from '../app';
|
|
||||||
|
|
||||||
describe('POST /users', () => {
|
## Git Commits
|
||||||
it('creates a new user', async () => {
|
|
||||||
const response = await request(app)
|
|
||||||
.post('/users')
|
|
||||||
.send({
|
|
||||||
email: 'test@example.com',
|
|
||||||
name: 'Test User',
|
|
||||||
password: 'password123',
|
|
||||||
})
|
|
||||||
.expect(201);
|
|
||||||
|
|
||||||
expect(response.body).toMatchObject({
|
**Format:** `<type>(<scope>): <subject>`
|
||||||
email: 'test@example.com',
|
**Types:** feat, fix, docs, style, refactor, test, chore
|
||||||
name: 'Test User',
|
**Example:** `feat(auth): add password reset functionality`
|
||||||
});
|
|
||||||
});
|
|
||||||
});
|
|
||||||
```
|
|
||||||
|
|
||||||
## Security Guidelines
|
## PR Checklist
|
||||||
|
|
||||||
### Authentication
|
- [ ] TypeScript compiles, ESLint passes
|
||||||
- Hash passwords with bcrypt (10-12 rounds)
|
- [ ] All tests pass, coverage >80%
|
||||||
- Use JWT with short expiration (15-60 min)
|
- [ ] No console.logs or debugger
|
||||||
- Implement refresh tokens
|
- [ ] Meaningful commits, clear PR description
|
||||||
- Store tokens in httpOnly cookies
|
- [ ] Documentation updated
|
||||||
|
|
||||||
### Authorization
|
|
||||||
- Check permissions on every protected route
|
|
||||||
- Implement RBAC or ABAC
|
|
||||||
- Never trust client-side checks
|
|
||||||
|
|
||||||
### Input Validation
|
|
||||||
- Validate ALL user inputs
|
|
||||||
- Sanitize HTML content
|
|
||||||
- Use parameterized queries for SQL
|
|
||||||
- Validate file uploads (type, size)
|
|
||||||
|
|
||||||
### API Security
|
|
||||||
- Enable CORS with specific origins
|
|
||||||
- Use rate limiting
|
|
||||||
- Implement CSRF protection
|
|
||||||
- Set security headers (Helmet.js)
|
|
||||||
|
|
||||||
## Performance Guidelines
|
|
||||||
|
|
||||||
### Frontend
|
|
||||||
- Code split routes and heavy components
|
|
||||||
- Lazy load images below the fold
|
|
||||||
- Use next/image for automatic optimization
|
|
||||||
- Memoize expensive computations
|
|
||||||
- Virtual scroll long lists
|
|
||||||
|
|
||||||
### Backend
|
|
||||||
- Add database indexes on frequently queried fields
|
|
||||||
- Use connection pooling
|
|
||||||
- Implement caching (Redis)
|
|
||||||
- Paginate large datasets
|
|
||||||
- Use background jobs for long tasks
|
|
||||||
|
|
||||||
## Git Commit Conventions
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Format: <type>(<scope>): <subject>
|
|
||||||
|
|
||||||
# Types:
|
|
||||||
feat: # New feature
|
|
||||||
fix: # Bug fix
|
|
||||||
docs: # Documentation only
|
|
||||||
style: # Code style (formatting, no logic change)
|
|
||||||
refactor: # Code refactoring
|
|
||||||
test: # Adding tests
|
|
||||||
chore: # Maintenance (deps, build, etc)
|
|
||||||
|
|
||||||
# Examples:
|
|
||||||
feat(auth): add password reset functionality
|
|
||||||
fix(api): handle null values in user endpoint
|
|
||||||
docs(readme): update setup instructions
|
|
||||||
refactor(components): extract Button component
|
|
||||||
```
|
|
||||||
|
|
||||||
## Code Review Checklist
|
|
||||||
|
|
||||||
Before submitting PR:
|
|
||||||
- [ ] TypeScript compiles without errors
|
|
||||||
- [ ] ESLint passes with no warnings
|
|
||||||
- [ ] All tests pass
|
|
||||||
- [ ] Test coverage meets requirements (>80%)
|
|
||||||
- [ ] No console.logs or debugger statements
|
|
||||||
- [ ] Meaningful commit messages
|
|
||||||
- [ ] PR description explains changes
|
|
||||||
- [ ] Documentation updated if needed
|
|
||||||
|
|
||||||
This living document should be updated as the team establishes new patterns and best practices.
|
|
||||||
|
|
@ -0,0 +1,222 @@
|
||||||
|
# <!-- Powered by BMAD™ Core -->
|
||||||
|
|
||||||
|
# Create Checkpoint Summary Task
|
||||||
|
|
||||||
|
## Purpose
|
||||||
|
Compact accumulated context from workflow phases into concise summaries that maintain essential information while reducing token usage for subsequent phases. Implements the "compaction strategy" from effective context engineering.
|
||||||
|
|
||||||
|
## When to Use
|
||||||
|
- After major decision points (architecture chosen, tech stack selected)
|
||||||
|
- Before transitioning between workflow phases
|
||||||
|
- After 5+ sequential agent interactions
|
||||||
|
- When detailed discussions need to be archived with key decisions preserved
|
||||||
|
|
||||||
|
## Prerequisites
|
||||||
|
- Completed phase with multiple artifacts or discussions
|
||||||
|
- Clear understanding of what decisions were made
|
||||||
|
- Identified next phase that needs minimal context to proceed
|
||||||
|
|
||||||
|
## Process
|
||||||
|
|
||||||
|
### 1. Identify Context to Compact
|
||||||
|
**Review Phase Outputs:**
|
||||||
|
- All artifacts created in the current phase
|
||||||
|
- Key decisions and their rationale
|
||||||
|
- Technical discussions and conclusions
|
||||||
|
- Rejected alternatives (if critical for future reference)
|
||||||
|
|
||||||
|
**Determine Signal vs Noise:**
|
||||||
|
- **High Signal** (keep): Final decisions, artifact paths, constraints, dependencies
|
||||||
|
- **Low Signal** (archive): Verbose discussions, iteration history, detailed pros/cons
|
||||||
|
|
||||||
|
### 2. Extract Essential Information
|
||||||
|
|
||||||
|
**Decisions Made:**
|
||||||
|
- What was decided (1-2 sentence summary)
|
||||||
|
- Brief rationale (why this choice)
|
||||||
|
- Reference to detailed documentation (file path)
|
||||||
|
|
||||||
|
**Artifacts Created:**
|
||||||
|
- File path and one-line description
|
||||||
|
- Who should reference it and when
|
||||||
|
- Critical information it contains
|
||||||
|
|
||||||
|
**Constraints & Dependencies:**
|
||||||
|
- Technical constraints discovered
|
||||||
|
- Dependencies between decisions
|
||||||
|
- Blockers or risks identified
|
||||||
|
|
||||||
|
### 3. Create Checkpoint Document
|
||||||
|
|
||||||
|
**Structure:**
|
||||||
|
```markdown
|
||||||
|
# Phase Checkpoint: [Phase Name]
|
||||||
|
|
||||||
|
## Context
|
||||||
|
[2-3 sentences describing what this phase accomplished]
|
||||||
|
|
||||||
|
## Key Decisions
|
||||||
|
1. **[Decision]** - [Brief rationale] → Details: `[artifact-path]`
|
||||||
|
2. **[Decision]** - [Brief rationale] → Details: `[artifact-path]`
|
||||||
|
|
||||||
|
## Artifacts Created
|
||||||
|
- `[path/to/artifact.md]` - [one-line description]
|
||||||
|
- `[path/to/artifact.md]` - [one-line description]
|
||||||
|
|
||||||
|
## Critical Constraints
|
||||||
|
- [Constraint or requirement that impacts next phase]
|
||||||
|
|
||||||
|
## Next Phase Requirements
|
||||||
|
[3-5 sentences of essential context needed for next phase]
|
||||||
|
|
||||||
|
## Detailed References
|
||||||
|
Full analysis and discussions archived in: `[archive-path]/`
|
||||||
|
```
|
||||||
|
|
||||||
|
**File Naming:** `docs/checkpoints/[phase-name]-checkpoint.md`
|
||||||
|
|
||||||
|
### 4. Validate Checkpoint Quality
|
||||||
|
|
||||||
|
**Completeness Check:**
|
||||||
|
- [ ] All major decisions documented with rationale
|
||||||
|
- [ ] All artifacts listed with paths
|
||||||
|
- [ ] Critical constraints identified
|
||||||
|
- [ ] Next phase has sufficient context
|
||||||
|
- [ ] Checkpoint is < 100 lines
|
||||||
|
|
||||||
|
**Context Reduction Check:**
|
||||||
|
- [ ] Checkpoint is 80%+ smaller than full phase context
|
||||||
|
- [ ] No duplicate information from artifacts
|
||||||
|
- [ ] References use paths, not content repetition
|
||||||
|
- [ ] Verbose discussions compressed to conclusions
|
||||||
|
|
||||||
|
### 5. Archive Detailed Context
|
||||||
|
|
||||||
|
**Move to Archive:**
|
||||||
|
- Long technical discussions → `docs/archive/[phase-name]/discussions/`
|
||||||
|
- Iteration history → `docs/archive/[phase-name]/iterations/`
|
||||||
|
- Rejected alternatives → `docs/archive/[phase-name]/alternatives/`
|
||||||
|
|
||||||
|
**Keep Active:**
|
||||||
|
- Checkpoint summary
|
||||||
|
- Final artifacts (architecture docs, specs, etc.)
|
||||||
|
- Critical decision records
|
||||||
|
|
||||||
|
## Checkpoint Templates by Phase
|
||||||
|
|
||||||
|
### Architecture Phase Checkpoint
|
||||||
|
```markdown
|
||||||
|
# Architecture Phase Checkpoint
|
||||||
|
|
||||||
|
## Context
|
||||||
|
Architecture designed for [project type]. Selected [stack] based on [key requirements].
|
||||||
|
|
||||||
|
## Key Decisions
|
||||||
|
1. **Frontend**: [Framework] - [Why] → `docs/architecture/system-architecture.md`
|
||||||
|
2. **Backend**: [Framework] - [Why] → `docs/architecture/system-architecture.md`
|
||||||
|
3. **Database**: [Database] - [Why] → `docs/architecture/system-architecture.md`
|
||||||
|
|
||||||
|
## Artifacts
|
||||||
|
- `docs/architecture/system-architecture.md` - Complete system design
|
||||||
|
- `docs/architecture/technology-stack-decision.md` - Stack rationale
|
||||||
|
|
||||||
|
## Constraints
|
||||||
|
- [Technical constraint]
|
||||||
|
- [Business constraint]
|
||||||
|
|
||||||
|
## For Implementation Phase
|
||||||
|
[Brief context about architecture approach, key patterns to follow, integration points]
|
||||||
|
```
|
||||||
|
|
||||||
|
### Feature Analysis Checkpoint
|
||||||
|
```markdown
|
||||||
|
# Feature Analysis Checkpoint
|
||||||
|
|
||||||
|
## Context
|
||||||
|
Analyzed feature: [feature name]. Identified impact on [affected areas].
|
||||||
|
|
||||||
|
## Key Decisions
|
||||||
|
1. **Implementation Approach**: [Approach] - [Why] → `docs/features/[name]/technical-spec.md`
|
||||||
|
2. **Database Changes**: [Changes] - [Why] → `docs/features/[name]/technical-spec.md`
|
||||||
|
|
||||||
|
## Artifacts
|
||||||
|
- `docs/features/[name]/requirements.md` - User requirements
|
||||||
|
- `docs/features/[name]/technical-spec.md` - Implementation details
|
||||||
|
|
||||||
|
## Constraints
|
||||||
|
- Must maintain compatibility with [system]
|
||||||
|
- Performance target: [metric]
|
||||||
|
|
||||||
|
## For Story Creation
|
||||||
|
[Brief guide for breaking into stories, key technical considerations, testing approach]
|
||||||
|
```
|
||||||
|
|
||||||
|
## Best Practices
|
||||||
|
|
||||||
|
### Be Ruthless in Compression
|
||||||
|
- If it's in an artifact, don't repeat it in checkpoint
|
||||||
|
- If it's a detail, reference the artifact
|
||||||
|
- If it's a conclusion, state it concisely
|
||||||
|
|
||||||
|
### Optimize for Next Agent
|
||||||
|
- What does the next agent absolutely need to know?
|
||||||
|
- What can they find in referenced artifacts?
|
||||||
|
- What context would waste their token budget?
|
||||||
|
|
||||||
|
### Maintain Traceability
|
||||||
|
- Always provide artifact paths for details
|
||||||
|
- Archive full discussions with clear paths
|
||||||
|
- Enable reconstruction of decisions if needed
|
||||||
|
|
||||||
|
## Common Pitfalls
|
||||||
|
|
||||||
|
**Over-Compression:**
|
||||||
|
- Don't omit critical constraints
|
||||||
|
- Don't skip key decision rationale
|
||||||
|
- Don't lose dependency information
|
||||||
|
|
||||||
|
**Under-Compression:**
|
||||||
|
- Don't repeat artifact contents
|
||||||
|
- Don't include full discussions
|
||||||
|
- Don't list all rejected options (only critical ones)
|
||||||
|
|
||||||
|
**Poor Structure:**
|
||||||
|
- Don't mix decisions with implementation details
|
||||||
|
- Don't bury critical info in long paragraphs
|
||||||
|
- Don't forget to reference artifact paths
|
||||||
|
|
||||||
|
## Success Criteria
|
||||||
|
|
||||||
|
**Effective Checkpoint:**
|
||||||
|
- [ ] < 100 lines total
|
||||||
|
- [ ] 80%+ smaller than original context
|
||||||
|
- [ ] All decisions captured with brief rationale
|
||||||
|
- [ ] All artifacts referenced by path
|
||||||
|
- [ ] Next phase agent can proceed with checkpoint + artifacts only
|
||||||
|
- [ ] Detailed context archived with clear paths
|
||||||
|
|
||||||
|
**Quality Validation:**
|
||||||
|
- [ ] Developer unfamiliar with phase can understand decisions
|
||||||
|
- [ ] No need to read full discussion history
|
||||||
|
- [ ] Critical information not lost
|
||||||
|
- [ ] Traceable to detailed artifacts
|
||||||
|
|
||||||
|
## Integration with Workflows
|
||||||
|
|
||||||
|
**In Workflow YAML:**
|
||||||
|
```yaml
|
||||||
|
- agent: analyst OR js-solution-architect OR sm
|
||||||
|
action: create_checkpoint
|
||||||
|
uses: create-checkpoint-summary task
|
||||||
|
creates: [phase-name]-checkpoint.md
|
||||||
|
notes: "Compact phase context into checkpoint summary. Archive detailed discussions. SAVE to docs/checkpoints/"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Next Phase References:**
|
||||||
|
```yaml
|
||||||
|
- agent: [next-agent]
|
||||||
|
requires: [phase-name]-checkpoint.md
|
||||||
|
notes: "Use checkpoint for context. Reference detailed artifacts as needed."
|
||||||
|
```
|
||||||
|
|
||||||
|
This task ensures long-horizon workflows maintain token efficiency while preserving essential information for downstream agents and future reference.
|
||||||
|
|
@ -17,14 +17,25 @@ workflow:
|
||||||
- agent: js-solution-architect
|
- agent: js-solution-architect
|
||||||
reviews: technical_impact
|
reviews: technical_impact
|
||||||
requires: feature-requirements.md
|
requires: feature-requirements.md
|
||||||
|
loads_if_needed:
|
||||||
|
- security-guidelines.md (IF authentication/authorization changes)
|
||||||
|
- best-practices.md (IF introducing new patterns)
|
||||||
|
- architecture-patterns.md (IF architectural changes)
|
||||||
notes: Assess technical impact on existing architecture. Identify affected components, database changes, API modifications, and integration points.
|
notes: Assess technical impact on existing architecture. Identify affected components, database changes, API modifications, and integration points.
|
||||||
|
|
||||||
|
- agent: js-solution-architect
|
||||||
|
action: create_checkpoint
|
||||||
|
uses: create-checkpoint-summary task
|
||||||
|
creates: architecture-impact-checkpoint.md
|
||||||
|
requires: technical_impact_review
|
||||||
|
notes: "Compact technical impact analysis into checkpoint: selected approach, affected components, risks, and constraints. Max 100 lines. SAVE to docs/features/[feature-name]/checkpoints/"
|
||||||
|
|
||||||
- agent: react-developer OR node-backend-developer OR api-developer
|
- agent: react-developer OR node-backend-developer OR api-developer
|
||||||
creates: technical-specification.md
|
creates: technical-specification.md
|
||||||
requires:
|
requires:
|
||||||
- feature-requirements.md
|
- feature-requirements.md
|
||||||
- technical_impact_review
|
- architecture-impact-checkpoint.md
|
||||||
notes: "Create detailed technical spec with file changes, new components/endpoints, types, tests, and implementation steps. SAVE to docs/features/[feature-name]/"
|
notes: "Create detailed technical spec with file changes, new components/endpoints, types, tests, and implementation steps. Reference checkpoint for architecture context. SAVE to docs/features/[feature-name]/"
|
||||||
|
|
||||||
- agent: sm
|
- agent: sm
|
||||||
creates: feature-stories.md
|
creates: feature-stories.md
|
||||||
|
|
@ -32,9 +43,16 @@ workflow:
|
||||||
uses: create-development-story task
|
uses: create-development-story task
|
||||||
notes: Break feature into implementable stories with clear acceptance criteria and DoD.
|
notes: Break feature into implementable stories with clear acceptance criteria and DoD.
|
||||||
|
|
||||||
|
- agent: sm
|
||||||
|
action: create_checkpoint
|
||||||
|
uses: create-checkpoint-summary task
|
||||||
|
creates: implementation-checkpoint.md
|
||||||
|
requires: feature-stories.md
|
||||||
|
notes: "Compact planning phase into checkpoint: story priorities, effort estimates, dependencies, and critical DoD criteria. Archive verbose specs. Max 100 lines. SAVE to docs/features/[feature-name]/checkpoints/"
|
||||||
|
|
||||||
workflow_end:
|
workflow_end:
|
||||||
action: begin_feature_implementation
|
action: begin_feature_implementation
|
||||||
notes: Feature fully specified and broken into stories. Developers can begin implementation following story sequence.
|
notes: Feature planning complete with compact checkpoint. Developers reference implementation-checkpoint.md + stories for context-efficient implementation.
|
||||||
|
|
||||||
story_flow:
|
story_flow:
|
||||||
- Create feature branch from main
|
- Create feature branch from main
|
||||||
|
|
|
||||||
|
|
@ -24,17 +24,28 @@ workflow:
|
||||||
- agent: js-solution-architect
|
- agent: js-solution-architect
|
||||||
creates: technology-stack-decision.md
|
creates: technology-stack-decision.md
|
||||||
requires: requirements-analysis.md
|
requires: requirements-analysis.md
|
||||||
|
loads_if_needed:
|
||||||
|
- technology-stack-guide.md (ALWAYS - for stack comparison)
|
||||||
|
- deployment-strategies.md (IF hosting decisions needed)
|
||||||
|
- security-guidelines.md (IF handling sensitive data)
|
||||||
optional_steps:
|
optional_steps:
|
||||||
- technology_research
|
- technology_research
|
||||||
- scalability_analysis
|
- scalability_analysis
|
||||||
- cost_estimation
|
- cost_estimation
|
||||||
notes: "Select appropriate technology stack based on requirements. Choose frontend framework, backend framework, database, hosting, and tools. SAVE OUTPUT: Copy to docs/architecture/ folder."
|
notes: "Select appropriate technology stack based on requirements. Choose frontend framework, backend framework, database, hosting, and tools. SAVE OUTPUT: Copy to docs/architecture/ folder."
|
||||||
|
|
||||||
|
- agent: js-solution-architect
|
||||||
|
action: create_checkpoint
|
||||||
|
uses: create-checkpoint-summary task
|
||||||
|
creates: stack-selection-checkpoint.md
|
||||||
|
requires: technology-stack-decision.md
|
||||||
|
notes: "Compact stack selection into checkpoint: chosen technologies, key rationale, and constraints. Max 100 lines. SAVE to docs/checkpoints/"
|
||||||
|
|
||||||
- agent: js-solution-architect
|
- agent: js-solution-architect
|
||||||
creates: system-architecture.md
|
creates: system-architecture.md
|
||||||
requires:
|
requires:
|
||||||
- requirements-analysis.md
|
- requirements-analysis.md
|
||||||
- technology-stack-decision.md
|
- stack-selection-checkpoint.md
|
||||||
optional_steps:
|
optional_steps:
|
||||||
- architecture_patterns_review
|
- architecture_patterns_review
|
||||||
- security_architecture
|
- security_architecture
|
||||||
|
|
@ -52,13 +63,22 @@ workflow:
|
||||||
condition: validation_issues_found
|
condition: validation_issues_found
|
||||||
notes: If validation finds issues, return to js-solution-architect to fix and re-export updated documents.
|
notes: If validation finds issues, return to js-solution-architect to fix and re-export updated documents.
|
||||||
|
|
||||||
|
- agent: js-solution-architect
|
||||||
|
action: create_checkpoint
|
||||||
|
uses: create-checkpoint-summary task
|
||||||
|
creates: architecture-complete-checkpoint.md
|
||||||
|
requires: system-architecture.md
|
||||||
|
condition: architecture_validated
|
||||||
|
notes: "Compact architecture phase into checkpoint: key architectural decisions, selected patterns, critical constraints, and setup requirements. Archive detailed analysis. Max 100 lines. SAVE to docs/checkpoints/"
|
||||||
|
|
||||||
project_setup_guidance:
|
project_setup_guidance:
|
||||||
action: initialize_project_structure
|
action: initialize_project_structure
|
||||||
notes: "Set up project following architecture document: Initialize monorepo (if needed), configure TypeScript, set up frontend (Next.js/Vite), backend (Express/Fastify/NestJS), and database (Prisma). Configure linting, formatting, and testing."
|
requires: architecture-complete-checkpoint.md
|
||||||
|
notes: "Set up project following checkpoint summary and architecture document. Initialize monorepo (if needed), configure TypeScript, set up frontend (Next.js/Vite), backend (Express/Fastify/NestJS), and database (Prisma). Configure linting, formatting, and testing."
|
||||||
|
|
||||||
workflow_end:
|
workflow_end:
|
||||||
action: move_to_story_development
|
action: move_to_story_development
|
||||||
notes: Architecture complete and validated. Set up development environment. Use Scrum Master to create implementation epics and stories from architecture document.
|
notes: Architecture phase complete with compact checkpoint. Developers reference architecture-complete-checkpoint.md for context-efficient story development.
|
||||||
|
|
||||||
mvp_sequence:
|
mvp_sequence:
|
||||||
- step: assess_mvp_scope
|
- step: assess_mvp_scope
|
||||||
|
|
@ -78,9 +98,16 @@ workflow:
|
||||||
requires: mvp-requirements.md
|
requires: mvp-requirements.md
|
||||||
notes: Create streamlined architecture focused on MVP features. Can skip detailed architecture for very simple MVPs and jump directly to stories.
|
notes: Create streamlined architecture focused on MVP features. Can skip detailed architecture for very simple MVPs and jump directly to stories.
|
||||||
|
|
||||||
|
- agent: js-solution-architect
|
||||||
|
action: create_checkpoint
|
||||||
|
uses: create-checkpoint-summary task
|
||||||
|
creates: mvp-checkpoint.md
|
||||||
|
requires: mvp-architecture.md
|
||||||
|
notes: "Compact MVP planning into checkpoint: core feature scope, minimal tech stack, and rapid implementation approach. Max 50 lines for lean MVP context. SAVE to docs/checkpoints/"
|
||||||
|
|
||||||
mvp_workflow_end:
|
mvp_workflow_end:
|
||||||
action: rapid_implementation
|
action: rapid_implementation
|
||||||
notes: MVP scope defined. Begin implementation focusing on core features. Use feature-development workflow for agile story creation and execution.
|
notes: MVP scope defined with compact checkpoint. Developers reference mvp-checkpoint.md for lean, context-efficient rapid implementation.
|
||||||
|
|
||||||
flow_diagram: |
|
flow_diagram: |
|
||||||
```mermaid
|
```mermaid
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue