К основному содержанию
скилл CX Codex

system-architecture — скилл для Claude Code: архитектура проекта

Скилл system-architecture помогает выбрать слои и границы модулей в связке FastAPI и React, а результат складывает в architecture.md и ADR.

MIT 125 установок ★ 8 обновлён 2026-02-06

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add hieutrtr/ai1-skills --skill system-architecture -a claude-code
Открыть на GitHub

Что делает system-architecture

Скилл ведёт проект через архитектурные решения: раскладывает бэкенд на роутеры, сервисы, репозитории и модели, а фронтенд — на страницы, лейауты, фичи, общие компоненты, хуки и api-слой. Импорты разрешены только в одну сторону: роутер видит сервис, сервис видит репозиторий, обратных зависимостей быть не должно.

Перед работой скилл ищет plan.md от project-planner и берёт объём задачи оттуда, иначе идёт от запроса. Дальше пять шагов: сформулировать проблему, собрать два-три варианта, прогнать их по таблице критериев (сопровождаемость и тестируемость весят больше всего), выбрать и записать решение вместе с отвергнутыми вариантами в ADR по шаблону references/architecture-decision-record-template.md. На выходе — architecture.md и файлы docs/adr/ADR-NNN-<title>.md.

Кода скилл не пишет. Из инструментов у него Read, Grep, Glob и Write, поэтому ни тестов, ни сборки он не запустит: реализация остаётся за python-backend-expert и react-frontend-expert, контракты API — за /api-design-patterns. Заявленная совместимость: Python 3.12+, FastAPI 0.115+, React 18+, SQLAlchemy 2.0+, TypeScript 5+.

Какие задачи решает

  • Решить, где живёт бизнес-логика: в роутере или в сервисе
  • Разложить React-приложение на страницы, фичи и общие компоненты
  • Сравнить два варианта хранения состояния и зафиксировать выбор
  • Записать принятое решение в ADR, чтобы через полгода не гадать
  • Спланировать изменение схемы БД до того, как начнутся миграции

Примеры запросов агенту

  • Продумай архитектуру нового модуля заказов: какие слои, где границы, что писать в architecture.md
  • Сравни два подхода к хранению состояния корзины и оформи решение как ADR в docs/adr/
  • Опиши схему БД для подписок и риски изменения, потом запиши ADR

Как установить system-architecture

1Через Skills CLI (Vercel)

npx skills add hieutrtr/ai1-skills --skill system-architecture -a claude-code

2Вручную: положить файлы

~/.claude/skills/system-architecture/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/system-architecture/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о system-architecture

Как установить system-architecture в Claude Code?

Выполните npx skills add hieutrtr/ai1-skills --skill system-architecture -a claude-code. Файл скилла появится в ~/.claude/skills/system-architecture/SKILL.md.

Что делает system-architecture?

Задаёт границы слоёв для FastAPI и React, сравнивает архитектурные варианты по таблице критериев и сохраняет выбор в architecture.md и ADR в docs/adr/.

Пишет ли он код?

Нет, инструменты ограничены чтением и записью файлов. Реализацию отдают python-backend-expert или react-frontend-expert, контракты API — /api-design-patterns.

Исходный текст

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

Похожие скиллы

Все скиллы по теме «Бэкенд и API» →
Python Backend Architecture Review rknall Скилл Python Backend Architecture Review для Claude Code: ревью архитектуры Python-бэкенда по системе, масштабируемости, безопасности и API. Разбирает документ проекта, находит узкие места в дизайне до релиза. CX Codex +1 528установок fastapi-production-architecture-cursorrules-prompt-file PatrickJS Правило fastapi-production-architecture-cursorrules-prompt-file для Cursor задаёт четырёхслойную архитектуру FastAPI-сервисов. Роутеры — до 10 строк, провайдеры изолированы. CX Codex +1 ★ 41 178звёзд репо System Architecture Reviewer microsoft Субагент System Architecture Reviewer разбирает архитектурные решения с учётом ограничений проекта, фиксирует компромиссы и помогает сохранить обоснование решений. Пригодится перед выбором архитектуры или оформлением ADR. CX Codex +1 ★ 1 627звёзд репо enterprise-user-management-system-ai reason-machines Скилл enterprise-user-management-system-ai разворачивает систему управления пользователями на связке React и Node.js с сервисом машинного обучения на FastAPI. CX Codex +1 249установок architecture-designer https://github.com/Jeffallan Скилл architecture-designer проектирует архитектуру распределённых систем, составляет диаграммы Mermaid и оформляет решения через ADR. Помогает сопоставить требования с шаблонами вроде микросервисов или монолита. CX Codex +1 8 500установок architecture официальный anthropics Скилл architecture для Claude Code: создаёт ADR, разбирает чужой дизайн системы — варианты, компромиссы, последствия. Закрывает выбор между технологиями. CX Codex +1 7 200установок

Из того же набора8

e2e-testing Скилл e2e-testing задаёт шаблоны E2E-тестирования на Playwright для веб-приложений на React и Python. Помогает строить надёжные сквозные сценарии и Page Objects. CX Codex +1 1 600установок code-review-security Скилл code-review-security для Claude Code проверяет изменения кода на уязвимости и секреты. Запускается при ревью pull request, проверке авторизации и обработке пользовательского ввода. CX Codex +1 446установок react-frontend-expert Скилл react-frontend-expert задаёт правила вёрстки React-компонентов на TypeScript, создания кастомных хуков и работы с TanStack Query. CX Codex +1 208установок react-testing-patterns Скилл react-testing-patterns задаёт правила тестирования компонентов и хуков React с помощью Testing Library, MSW и Vitest. Помогает писать надёжные проверки без привязки к деталям реализации. CX Codex +1 141установок python-backend-expert Скилл python-backend-expert задаёт паттерны бэкенда на FastAPI, SQLAlchemy 2.0 и Pydantic v2. Помогает писать асинхронные эндпоинты, репозитории и миграции Alembic. CX Codex +1 138установок ui-design-system Скилл ui-design-system задаёт единые правила для UI в React/TypeScript: токены, отступы, типографику и доступность. Нужен при создании и ревью компонентов. CX Codex +1 124установок pytest-patterns Скилл pytest-patterns для Claude Code помогает писать тесты Python-бэкенда на pytest. Он включается при работе с сервисами, репозиториями и API FastAPI. CX Codex +1 123установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой