VidyFoo/antigravity-skill-engine / .agent/skills/1-dev/fullstack-guide
fullstack-guide
Verified全栈开发规范百科全书 (React/TS/Node/Supabase). Modern patterns including Suspense, lazy loading, useSuspenseQuery, file organization with features directory, performance optimization, and TypeScript best practices. Use when creating components, pages, features, fetching data, styling, routing, or working with frontend/backend code.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.5 KB |
| resources/common-patterns.md | markdown | 4.8 KB |
| resources/component-patterns.md | markdown | 4.5 KB |
| resources/data-fetching.md | markdown | 5.4 KB |
| resources/file-organization.md | markdown | 4.9 KB |
| resources/loading-and-error-states.md | markdown | 5.5 KB |
| resources/resources/architecture-overview.md | markdown | 7.8 KB |
| resources/resources/async-and-errors.md | markdown | 6.1 KB |
| resources/resources/testing-guide.md | markdown | 6.9 KB |
| resources/resources/validation-patterns.md | markdown | 7.8 KB |
| resources/routing-guide.md | markdown | 4.7 KB |
| resources/styling-guide.md | markdown | 4.6 KB |
| resources/typescript-standards.md | markdown | 5.4 KB |
resources/resources/architecture-overview.md
View on GitHub# Architecture Overview - Backend Services
Complete guide to the layered architecture pattern used in backend microservices.
## Table of Contents
- [Layered Architecture Pattern](#layered-architecture-pattern)
- [Request Lifecycle](#request-lifecycle)
- [Directory Structure](#directory-structure)
- [Separation of Concerns](#separation-of-concerns)
---
## Layered Architecture Pattern
### The Four Layers
```
┌─────────────────────────────────────┐
│ HTTP Request │
└───────────────┬─────────────────────┘
↓
┌─────────────────────────────────────┐
│ Layer 1: ROUTES │
│ - Route definitions only │
│ - Middleware registration │
│ - Delegate to controllers │
│ - NO business logic │
└───────────────┬─────────────────────┘
↓
┌─────────────────────────────────────┐
│ Layer 2: CONTROLLERS │
│ - Input validation (Zod) │
│ - Call services │
│ - Response formatting │
│ - Error handling boundaries │
└───────────────┬─────────────────────┘
↓
┌─────────────────────────────────────┐
│ Layer 3: SERVICES │
│ - Business logic │
│ - Orchestration │
│ - Cross-service calls │
│ - Error handling │
└───────────────┬─────────────────────┘
↓
┌─────────────────────────────────────┐
│ Layer 4: REPOSITORIES │
│ - Database access │
│ - PrismaService interactions │
│ - Data transformation │
│ - NO business logic │
└─────────────────────────────────────┘
```
---
## Request Lifecycle
### Full Request Flow Example
```typescript
// 1. Request arrives at route
router.post('/users', middleware, (req, res) => userController.create(req, res));
// 2. Controller validates and delegates
async create(req: Request, res: Response) {
try {
const validated = createUserSchema.parse(req.body); // Validation
const user = await this.userService.create(validated); // Delegate
this.handleSuccess(res, user, 'User created'); // Response
} catch (error) {
this.handleError(error, res, 'create'); // Error handling
}
}
// 3. Service contains business logic
async create(data: CreateUserDTO): Promise<User> {
const existing = await this.userRepository.findByEmail(data.email);
if (existing) throw new ConflictError('Email already exists');
return await this.userRepository.create(data);
}
// 4. Repository handles database
async create(data: CreateUserDTO): Promise<User> {
return PrismaService.main.user.create({ data });
}
```
---
## Directory Structure
### Recommended Layout
```
src/
├── routes/ # Route definitions
│ ├── index.ts # Route aggregator
│ ├── userRoutes.ts
│ └── authRoutes.ts
├── controllers/ # Request handlers
│ ├── BaseController.ts
│ ├── UserController.ts
│ └── AuthController.ts
├── services/ # Business logic
│ ├── UserService.ts
│ └── AuthService.ts
├── repositories/ # Data access
│ ├── UserRepository.ts
│ └── BaseRepository.ts
├── schemas/ # Zod validation schemas
│ ├── userSchemas.ts
│ └── authSchemas.ts
├── middleware/ # Express middleware
│ ├── authMiddleware.ts
│ └── errorMiddleware.ts
├── errors/ # Custom error types
│ ├── AppError.ts
│ └── HttpErrors.ts
└── utils/ # Utilities
└── asyncErrorWrapper.ts
```
---
## Separation of Concerns
### Route Layer
**DO:**
- Define endpoints
- Register middleware
- Delegate to controllers
**DON'T:**
- Put business logic
- Access database
- Format responses
```typescript
// ✅ Good route
router.post('/users',
authMiddleware,
(req, res) => userController.create(req, res)
);
// ❌ Bad route - business logic in route
router.post('/users', async (req, res) => {
const user = await prisma.user.create({ data: req.body });
res.json(user);
});
```
### Controller Layer
**DO:**
- Validate input
- Call services
- Format responses
- Handle errors
**DON'T:**
- Implement business logic
- Access database directly
- Make cross-service calls
```typescript
// ✅ Good controller
async create(req: Request, res: Response) {
try {
const validated = schema.parse(req.body);
const result = await this.service.create(validated);
this.handleSuccess(res, result);
} catch (error) {
this.handleError(error, res);
}
}
```
### Service Layer
**DO:**
- Implement business logic
- Orchestrate operations
- Throw appropriate errors
- Call repositories
**DON'T:**
- Handle HTTP concerns
- Format responses
- Access req/res
```typescript
// ✅ Good service
async create(data: CreateDTO): Promise<Entity> {
// Business rule validation
const exists = await this.repository.findByEmail(data.email);
if (exists) throw new ConflictError('Email exists');
// Business logic
return this.repository.create(data);
}
```
### Repository Layer
**DO:**
- Execute database queries
- Transform data models
- Handle database errors
**DON'T:**
- Implement business logic
- Validate business rules
- Know about HTTP
```typescript
// ✅ Good repository
async findByEmail(email: string): Promise<User | null> {
return PrismaService.main.user.findUnique({ where: { email } });
}
async create(data: CreateUserDTO): Promise<User> {
return PrismaService.main.user.create({ data });
}
```
---
## Complete Example: User Creation
**Route:**
```typescript
router.post('/users',
authMiddleware,
auditMiddleware,
(req, res) => userController.create(req, res)
);
```
**Controller:**
```typescript
async create(req: Request, res: Response): Promise<void> {
try {
const validated = createUserSchema.parse(req.body);
const user = await this.userService.create(validated);
this.handleSuccess(res, user, 'User created');
} catch (error) {
this.handleError(error, res, 'create');
}
}
```
**Service:**
```typescript
async create(data: CreateUserDTO): Promise<User> {
const existing = await this.userRepository.findByEmail(data.email);
if (existing) throw new ConflictError('Email already exists');
return await this.userRepository.create(data);
}
```
**Repository:**
```typescript
async create(data: CreateUserDTO): Promise<User> {
return PrismaService.main.user.create({ data });
}
async findByEmail(email: string): Promise<User | null> {
return PrismaService.main.user.findUnique({ where: { email } });
}
```
**Notice:** Each layer has clear, distinct responsibilities!
---
**Related Files:**
- [SKILL.md](../SKILL.md) - Main guide
- [validation-patterns.md](validation-patterns.md) - Input validation
- [async-and-errors.md](async-and-errors.md) - Error handling
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |