lidge-jun/codexclaw / plugins/codexclaw/skills/dev-backend
cxc-dev-backend
FlaggedUse for APIs, servers and app databases. Triggers: REST, GraphQL, migration, query optimization, middleware, caching, queues, 백엔드, API 작업, 마이그레이션, 쿼리 최적화.
references/core/architecture.md
View on GitHub# Architecture Patterns
When to use which pattern, how to structure code, and when to split.
Synthesized from dev-backend + dev-scaffolding (Lidge Standard) + senior-architect (alirezarezvani).
---
## Layered Architecture (Default)
```
Routes → Controllers → Services → Repositories → Database
```
### Layer Rules
| Layer | Responsibility | Receives | Returns |
| ------------ | ------------------------------- | ---------- | ----------- |
| Routes | URL patterns + middleware chain | HTTP req | (delegates) |
| Controllers | Parse input, format output | req/res | HTTP resp |
| Services | Business logic (input validated at controller/trust boundary) | Plain data | Plain data |
| Repositories | Database access | Queries | Entities |
**Iron Rule:** Services never receive `req`/`res`. Services never write raw SQL.
---
## When to Split
| Signal | Action |
| ------------------------------------------ | ------------------------------------ |
| Module needs different scaling | Extract to separate service |
| Separate team needs independent deploy | Extract to microservice |
| Technology mismatch (Python ML + Node API) | Separate per technology |
| File > 500 lines | Split by domain within same layer |
| Feature > 10 files | Create sub-folders by responsibility |
| **Everything else** | Keep in monolith |
---
## Pattern Selection Matrix
| Requirement | Recommended Pattern |
| ---------------------------- | ----------------------------- |
| Rapid MVP development | Modular Monolith |
| Independent team deployment | Microservices |
| Complex domain logic | Domain-Driven Design (DDD) |
| High read/write ratio diff | CQRS |
| Audit trail required | Event Sourcing |
| Third-party integrations | Hexagonal / Ports & Adapters |
| Different scaling per module | Service-Oriented Architecture |
---
## Monolith vs Microservices Decision
### Choose Monolith When:
- Team < 10 developers
- Domain boundaries unclear
- Rapid iteration is priority
- Operational complexity must be minimized
- Shared database acceptable
### Choose Microservices When:
- Teams own services end-to-end
- Independent deployment critical
- Different scaling per component
- Technology diversity needed
- Domain boundaries well understood
### Hybrid Approach (Recommended):
Start modular monolith → extract when:
1. A module has significantly different scaling needs
2. A team needs independent deployment
3. Technology constraints require separation
---
## Database Selection
| Characteristic | Points to SQL | Points to NoSQL |
| ------------------------------ | :-----------: | :-------------: |
| Structured with relationships | ✓ | |
| ACID transactions required | ✓ | |
| Flexible/evolving schema | | ✓ |
| Document-oriented data | | ✓ |
| High write throughput (>10K/s) | | ✓ (specialized) |
Quick reference:
```
PostgreSQL → Default choice for most applications
MongoDB → Document store, flexible schema
Redis → Caching, sessions, real-time
DynamoDB → Serverless, auto-scaling, AWS
TimescaleDB → Time-series with SQL
```
---
## SOLID Principles (Quick Reference)
| Principle | Rule |
| ------------------------- | ------------------------------------------- |
| **S**ingle Responsibility | One class = one reason to change |
| **O**pen/Closed | Open for extension, closed for modification |
| **L**iskov Substitution | Subtypes must be substitutable |
| **I**nterface Segregation | Small, focused interfaces |
| **D**ependency Inversion | Depend on abstractions, not concretions |
---
## The Lidge Standard (Project Scaffolding)
Three pillars every project must follow:
1. **Screaming Architecture** — folder names reveal what the app does (`stock-price/`, `auth/`, `report/`)
2. **Colocation** — related files live together (logic + test + schema in same folder)
3. **Barrel Export** — each feature exposes a single entry point
### Project Skeleton
```
<project>/
├── AGENTS.md # AI context (propose in plan — do not create silently per dev §0.5)
├── README.md # Human overview
├── .env.example # Env template (never commit .env)
│ ├── _plan/ # Active plans
│ ├── _fin/ # Completed work
│ └── str_func/ # Module documentation
├── src/ # Feature-based layout
│ ├── auth/ # Feature folder
│ │ ├── auth.tool.ts
│ │ ├── auth.test.ts
│ │ └── index.ts # Public API barrel (package boundary only — see dev-architecture §5)
│ └── shared/ # Truly shared utils only
├── config/
├── docs/
└── tests/e2e/
```
### Feature Module Files
| Language | Main File | Test File | Barrel |
| ---------- | -------------- | -------------- | ------------- |
| TypeScript | `name.tool.ts` | `name.test.ts` | `index.ts` |
| Python | `name_tool.py` | `test_name.py` | `__init__.py` |
| Go | `name.go` | `name_test.go` | *(package)* |
---
## Architecture Decision Records (ADRs)
For significant decisions, create:
```markdown
# ADR-001: [Decision Title]
## Context
[Why this decision is needed]
## Decision
[What we decided]
## Alternatives Considered
[What we rejected and why]
## Consequences
[Trade-offs accepted]
```
Store in `docs/adr/` or another repository source-of-truth planning location.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| Agent Cost Reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| Agent Cost Reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |