system-architecture — Claude Code skill: what it does, how to install
system-architecture guides the design phase of a Python and React project: layer boundaries, state ownership, schema plans, and an ADR to go with them.
MIT 125 installs ★ 8 updated 2026-02-06
npx skills add hieutrtr/ai1-skills --skill system-architecture -a claude-codeWhat system-architecture does
On the design side of a Python and React stack, this skill does the paperwork: it names the layers, sets the allowed import direction, and writes the result down. Backend runs routers, then services, then repositories, then models. A router never reaches the database directly, and a repository holds no business rules.
The frontend gets the same shape: pages, layouts, features, shared components, hooks, api and types, with imports flowing one way. For a real decision the skill walks five steps. State the problem, list two or three options, score them on maintainability, testability, performance, team familiarity, cost and flexibility, then record the winner and the rejected alternatives in an ADR. It looks for plan.md from project-planner first; output goes to architecture.md and docs/adr/ADR-NNN-<title>.md.
Writing code is out of scope. Its toolset is Read, Grep, Glob and Write, so nothing gets executed or tested here. python-backend-expert and react-frontend-expert take the implementation, /api-design-patterns takes the API contracts. Stated compatibility: Python 3.12+, FastAPI 0.115+, React 18+, SQLAlchemy 2.0+, TypeScript 5+.
What it helps with
- Decide where business logic belongs before the first endpoint is written
- Split a growing React app into pages, features and shared components
- Weigh two state-management options and record why one lost
- Write an ADR that still makes sense after the next refactor
- Plan a schema change before touching migrations
Example prompts for the agent
- Sketch the architecture for a new billing module and write it to
architecture.md - Compare two ways to hold cart state and record the pick as an ADR under
docs/adr/ - Plan the database schema for subscriptions, with the trade-offs, then save the decision
How to install system-architecture
1Skills CLI (Vercel)
npx skills add hieutrtr/ai1-skills --skill system-architecture -a claude-code2Manually: put the files in place
~/.claude/skills/system-architecture/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/system-architecture/
1Skills CLI (Vercel)
npx skills add hieutrtr/ai1-skills --skill system-architecture -a codex2Manually: put the files in place
.agents/skills/system-architecture/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add hieutrtr/ai1-skills --skill system-architecture -a cursor2Manually: put the files in place
.cursor/skills/system-architecture/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install hieutrtr/ai1-skills skills/system-architecture2Manually: put the files in place
.github/skills/system-architecture/SKILL.md1Skills CLI (Vercel)
npx skills add hieutrtr/ai1-skills --skill system-architecture -a gemini-cli2Platform CLI
gemini skills install https://github.com/hieutrtr/ai1-skills --path skills/system-architectureManually: put the files in place
.devin/skills/system-architecture/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add hieutrtr/ai1-skills --skill system-architecture -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about system-architecture
How do I install system-architecture in Claude Code?
Run npx skills add hieutrtr/ai1-skills --skill system-architecture -a claude-code. The skill lands in ~/.claude/skills/system-architecture/SKILL.md.
What does system-architecture do?
It sets layer boundaries for a FastAPI backend and a React frontend, scores design options against a criteria table, and saves the outcome in architecture.md plus ADRs under docs/adr/.
Does it write the code too?
No. It only reads and writes files, so implementation goes to python-backend-expert or react-frontend-expert, and API contracts to /api-design-patterns.
Source text
SKILL.md · MIT
---
name: system-architecture
description: >-
System architecture guidance for Python/React full-stack projects. Use during
the design phase when making architectural decisions — component boundaries, service
layer design, data flow patterns, database schema planning, and technology trade-off
analysis. Covers FastAPI layer architecture (Routes/Services/Repositories/Models),
React component hierarchy, state management, and cross-cutting concerns (auth, errors,
logging). Produces architecture documents and ADRs. Does NOT cover implementation
(use python-backend-expert or react-frontend-expert) or API contract design
(use api-design-patterns).
license: MIT
compatibility: 'Python 3.12+, FastAPI 0.115+, React 18+, SQLAlchemy 2.0+, TypeScript 5+'
metadata:
author: platform-team
version: '1.0.0'
sdlc-phase: architecture
allowed-tools: Read Grep Glob Write
context: fork
---
# System Architecture
## When to Use
Activate this skill when:
- Designing a new module, service, or major feature that requires structural decisions
- Choosing between architectural approaches (e.g., where to place logic, how to structure data flow)
- Planning database schema changes or refactoring existing schema
- Making frontend state management decisions (server state vs client state, context vs store)
- Evaluating technology trade-offs for a new capability
- Creating or reviewing Architecture Decision Records (ADRs)
- Setting up a new project or major subsystem from scratch
**Input:** If `plan.md` exists (from `project-planner`), read it for context about the feature scope and affected modules. Otherwise, work from the user's request directly.
**Output:** Write architecture decisions to `architecture.md` and create ADRs in `docs/adr/ADR-NNN-<title>.md`. Tell the user: "Architecture written to `architecture.md`. Run `/api-design-patterns` for API contracts or `/task-decomposition` for implementation tasks."
Do NOT use this skill for:
- Writing implementation code (use `python-backend-expert` or `react-frontend-expert`)
- API contract design or endpoint specifications (use `api-design-patterns`)
- Testing patterns or strategies (use `pytest-patterns` or `react-testing-patterns`)
- Deployment or infrastructure decisions (use `docker-best-practices` or `deployment-pipeline`)
## Instructions
### Project Layer Architecture
The standard Python/React full-stack architecture follows a layered pattern with strict dependency direction.
#### Backend Layers (FastAPI)
```
HTTP Request
↓
┌─────────────────────┐
│ Routers (routes/) │ ← HTTP concerns: request parsing, response formatting, status codes
│ │ Uses: Depends() for injection, Pydantic schemas for validation
├─────────────────────┤
│ Services │ ← Business logic: orchestration, validation rules, domain operations
│ (services/) │ No HTTP awareness. Raises domain exceptions, not HTTPException.
├─────────────────────┤
│ Repositories │ ← Data access: queries, CRUD operations, database interactions
│ (repositories/) │ No business logic. Returns model instances or None.
├─────────────────────┤
│ Models (models/) │ ← SQLAlchemy ORM models: table definitions, relationships, indexes
│ Schemas (schemas/) │ ← Pydantic v2 models: request/response contracts, validation
└─────────────────────┘
↓
Database
```
**Dependency direction rules:**
- Routers depend on Services (never on Repositories directly)
- Services depend on Repositories (never on Routers)
- Repositories depend on Models (never on Services)
- Schemas are shared across layers but define no dependencies themselves
- Never skip layers: no direct database access from routes
**Dependency injection pattern:**
```python
# Router depends on Service via Depends()
@router.post("/users", response_model=UserResponse)
async def create_user(
data: UserCreate,
service: UserService = Depends(get_user_service),
) -> UserResponse:
return await service.create_user(data)
# Service depends on Repository via constructor injection
class UserService:
def __init__(self, repo: UserRepository) -> None:
self.repo = repo
# Repository depends on AsyncSession via Depends()
class UserRepository:
def __init__(self, session: AsyncSession) -> None:
self.session = session
```
#### Frontend Layers (React/TypeScript)
```
┌─────────────────────┐
│ Pages (pages/) │ ← Route-level components: data fetching, layout composition
├─────────────────────┤
│ Layouts │ ← Page structure: navigation, sidebars, content areas
│ (layouts/) │
├─────────────────────┤
│ Features │ ← Domain-specific: UserProfile, OrderList, ChatPanel
│ (features/) │ Composed from shared components + hooks
├─────────────────────┤
│ Shared Components │ ← Reusable UI: Button, Modal, Table, Form, Input
│ (components/) │ No business logic. Configurable via props.
├─────────────────────┤
│ Hooks (hooks/) │ ← Custom hooks: useAuth, usePagination, useDebounce
│ API (api/) │ ← API client functions, TanStack Query configurations
├─────────────────────┤
│ Types (types/) │ ← Shared TypeScript interfaces and type definitions
└─────────────────────┘
```
**Component dependency direction:**
- Pages import Features and Layouts
- Features import Shared Components and Hooks
- Shared Components import only other Shared Components and Types
- Hooks import API functions and Types
- API functions import Types only
### Decision Framework
When facing architectural decisions, follow this structured process:
#### Step 1: Define the Problem
- What capability is needed?
- What are the non-functional requirements? (performance, scalability, maintainability)
- What constraints exist? (team size, timeline, existing infrastructure)
#### Step 2: Identify Options
- List 2-3 viable architectural approaches
- For each option, document:
- How it works (brief technical description)
- Advantages
- Disadvantages
- Risks
#### Step 3: Evaluate Against Criteria
| Criterion | Weight | Description |
|-----------|--------|-------------|
| Maintainability | High | Can the team understand, modify, and debug this easily? |
| Testability | High | Can each component be tested in isolation? |
| Performance | Medium | Does it meet latency and throughput requirements? |
| Team familiarity | Medium | Does the team have experience with this approach? |
| Operational cost | Low | What are the infrastructure and maintenance costs? |
| Future flexibility | Low | How easily can this evolve as requirements change? |
#### Step 4: Decide and Document
- Choose the option that best satisfies the weighted criteria
- Document the decision in an ADR (see `references/architecture-decision-record-template.md`)
- Record what was NOT chosen and why — this context is valuable for future decisions
#### Step 5: Communicate
- Share the ADR with the team
- Identify any migration or rollout steps needed
- Flag reversibility: is this a one-way door or a two-way door?
### Database Schema Design
#### Design Principles
1. **Start normalized (3NF)** — Denormalize only for proven performance bottlenecks, not speculation
2. **One migration per logical change** — Each Alembic migration should represent a single, coherent schema modification
3. **Always include downgrade** — Every migration must have a working `downgrade()` function
4. **Index strategically:**
- Primary keys (automatic)
- Foreign keys (always)
- Columns in WHERE clauses of frequent queries
- Composite indexes for multi-column lookups
- Partial indexes for filtered queries (e.g., `WHERE is_active = true`)
#### SQLAlchemy 2.0 Async Patterns
```python
# Model definition with Mapped types (SQLAlchemy 2.0 style)
class User(Base):
__tablename__ = "users"
id: Mapped[int] = mapped_column(primary_key=True)
email: Mapped[str] = mapped_column(String(255), unique=True, index=True)
is_active: Mapped[bool] = mapped_column(default=True)
created_at: Mapped[datetime] = mapped_column(server_default=func.now())
# Relationships: ALWAYS use eager loading with async
posts: Mapped[list["Post"]] = relationship(
back_populates="author",
lazy="selectin", # or "joined" — NEVER "lazy" with async
)
```
**Async session rules:**
- One `AsyncSession` per request — never share across concurrent tasks
- Use `async with` context manager for automatic cleanup
- Map session boundaries to transaction boundaries
- Use `selectin` or `joined` loading — lazy loading is incompatible with asyncio
- Use `run_sync()` only as a last resort for legacy code
#### Migration Planning
1. Schema change → Generate migration: `alembic revision --autogenerate -m "description"`
2. Review generated migration — verify column types, indexes, constraints
3. Test upgrade: `alembic upgrade head`
4. Test downgrade: `alembic downgrade -1`
5. Test data preservation: ensure existing data survives the round-trip
### Frontend Architecture
#### State Management Decision Tree
```
Is the data from the server?
├── YES → Use TanStack Query (useQuery, useMutation)
│ Configure staleTime, gcTime, query keys
│
└── NO → Is it needed across multiple components?
├── YES → Is it complex with actions/reducers?
│ ├── YES → Use Zustand store
│ └── NO → Use React Context
│
└── NO → Use useState / useReducer locally
```
**TanStack Query conventions:**
- Query keys: `[resource, ...identifiers]` (e.g., `["users", userId]`, `["posts", { page, limit }]`)
- Use `queryOptions()` factory to centralize key + fn definitions — prevents copy-paste key errors
- Set `staleTime` based on data freshness needs (default 0 is too aggressive for most cases)
- Invalidate with `invalidateQueries()` after mutations — never manual `refetch()`
- Handle all states: `isPending`, `isError`, `data`
**Component design rules:**
- Props for configuration, hooks for data
- Lift state only as high as needed — no premature context creation
- Keep components under 200 lines — extract sub-components or custom hooks when larger
- Use `children` and composition over deep prop drilling
#### Routing Structure
Organize routes to mirror the URL structure:
```
src/
├── pages/
│ ├── HomePage.tsx → /
│ ├── LoginPage.tsx → /login
│ ├── users/
│ │ ├── UserListPage.tsx → /users
│ │ └── UserDetailPage.tsx → /users/:id
│ └── settings/
│ └── SettingsPage.tsx → /settings
```
### Cross-Cutting Concerns
#### Authentication Flow
```
Login Request
↓
Backend: Validate credentials → Generate JWT (access + refresh tokens)
↓
Frontend: Store access token in memory, refresh token in httpOnly cookie
↓
API Calls: Attach access token via Authorization header
↓
Token Expired: Use refresh token to obtain new access token
↓
Refresh Failed: Redirect to login
```
**Architecture decisions for auth:**
- Access tokens: short-lived (15-30 min), stored in memory (not localStorage)
- Refresh tokens: longer-lived (7-30 days), stored in httpOnly cookie
- Backend: FastAPI `Depends()` chain for token validation → user extraction → permission check
- Frontend: Auth context providing `user`, `login()`, `logout()`, `isAuthenticated`
#### Error Handling Strategy
Errors should be handled at the appropriate layer:
| Layer | Error Type | Action |
|-------|-----------|--------|
| Router | `HTTPException` | Return HTTP error response with status code |
| Service | Domain exceptions | Raise custom exceptions (e.g., `UserNotFoundError`) |
| Repository | Database exceptions | Catch and re-raise as domain exceptions or let propagate |
| Frontend | API errors | Display user-friendly messages, retry where appropriate |
**Backend exception hierarchy:**
```python
class AppError(Exception):
"""Base application error."""
class NotFoundError(AppError):
"""Resource not found."""
class ConflictError(AppError):
"""Resource conflict (duplicate, version mismatch)."""
class ValidationError(AppError):
"""Business rule violation."""
```
Router-level exception handler maps domain exceptions to HTTP responses:
```python
@app.exception_handler(NotFoundError)
async def not_found_handler(request: Request, exc: NotFoundError):
return JSONResponse(status_code=404, content={"detail": str(exc)})
```
#### Logging Architecture
**Backend (structlog):**
- Structured JSON logs in production
- Human-readable console in development
- Bind request context (request_id, user_id) at middleware level
- Log at service layer (business events), not repository layer (too noisy)
- Use log levels: DEBUG (development only), INFO (business events), WARNING (recoverable issues), ERROR (failures requiring attention)
**Frontend:**
- `console.*` in development
- Structured error reporting to backend or Sentry in production
- Log user actions for debugging, not for analytics
#### Configuration Management
**Backend (pydantic-settings):**
```python
class Settings(BaseSettings):
model_config = SettingsConfigDict(env_file=".env")
database_url: str
redis_url: str = "redis://localhost:6379"
jwt_secret: str
debug: bool = False
```
**Frontend (environment variables):**
- `VITE_API_URL` for API base URL
- Build-time injection via Vite's `import.meta.env`
- No secrets in frontend environment variables
### Output Files
#### architecture.md
Write the architecture document to `architecture.md` at the project root:
```markdown
# Architecture: [Feature/System Name]
## Overview
[1-2 sentence summary of the architectural approach]
## Layer Structure
[Backend and frontend layer descriptions from this skill's patterns]
## Key Decisions
[Summary of decisions made, with links to ADRs]
## Database Schema
[Entity descriptions, relationships, key indexes]
## Cross-Cutting Concerns
[Auth, error handling, logging approach]
## Next Steps
- Run `/api-design-patterns` to define API contracts
- Run `/task-decomposition` to create implementation tasks
```
#### ADRs
For each significant decision, create an ADR in `docs/adr/`:
```markdown
# ADR-NNN: [Decision Title]
## Status
Accepted | Proposed | Superseded
## Context
[Why this decision is needed]
## Decision
[What we decided]
## Consequences
[Positive and negative outcomes]
```
Number ADRs sequentially (ADR-001, ADR-002, etc.).
## Examples
### Architecture Decision: Real-Time Notifications
**Problem:** The application needs real-time notifications for users (new messages, status updates).
**Options evaluated:**
| Option | Pros | Cons |
|--------|------|------|
| **WebSocket** | True bidirectional, low latency | Complex connection management, harder to scale |
| **Server-Sent Events (SSE)** | Simple, HTTP-based, auto-reconnect | Unidirectional (server→client only), limited browser connections |
| **Polling** | Simplest implementation, works everywhere | Higher latency, unnecessary server load |
**Decision:** WebSocket for this use case.
**Rationale:** Notifications require low latency and the system will eventually need bidirectional communication (typing indicators, presence). SSE would work for notifications alone but would require a separate solution for future bidirectional needs. Polling introduces unacceptable latency for real-time UX.
**Architecture:**
- Backend: FastAPI WebSocket endpoint with `ConnectionManager` class
- Frontend: Custom `useWebSocket` hook with automatic reconnection
- Scaling: Redis pub/sub for multi-instance message distribution
- Persistence: Store notifications in database for offline users
- Fallback: REST endpoint for notification history and initial load
See `references/architecture-decision-record-template.md` for the full ADR format.
## Edge Cases
### Monolith vs Microservices
**Default to modular monolith** for teams smaller than 10 developers. A modular monolith provides:
- Clear module boundaries without network overhead
- Shared database with module-specific schemas
- Easy refactoring and code navigation
- Simple deployment and debugging
**Consider microservices** only when:
- Independent scaling is required for specific components
- Different modules need different technology stacks
- Team size exceeds 10 and ownership boundaries are clear
- Deployment independence is a business requirement
**Migration path:** Design module boundaries in the monolith as if they were services (no direct cross-module database access, communicate via service interfaces). This makes extraction to microservices straightforward when needed.
### When to Break the Layer Pattern
The strict Router → Service → Repository pattern should be followed for standard CRUD operations. Acceptable exceptions:
- **Background tasks:** May call services directly without going through a router
- **Event handlers:** Domain event listeners may call services from any context
- **CLI commands:** Management scripts may access services or repositories directly
- **Migrations:** Data migrations may access models directly (no service/repo layer needed)
- **Health checks:** May access the database directly for simple connectivity verification
In all cases, business logic should still live in the service layer — these exceptions are about the entry point, not about bypassing business rules.
### Evolving Architecture
When the architecture needs to change:
1. Write an ADR documenting the motivation and the proposed change
2. Identify all affected modules and their dependencies
3. Plan an incremental migration — never big-bang rewrites
4. Maintain backward compatibility during transition (strangler fig pattern)
5. Set a deadline for completing the migration and removing legacy code
© platform-team · MIT · hieutrtr/ai1-skills