# Architecture

## Allowed call graph

```
UI (user-h5 / mini-program)
  → packages/sdk
  → API Handler
  → Service
  → Repository
  → Database
```

## Forbidden

- Handler → Database (skip Service/Repository)
- UI → Database
- UI direct `fetch` to raw URLs (must use `@yuxingu/sdk` or `src/api` thin wrapper)
- Service importing Handler
- Circular package imports
- Giant `utils` / `common` dump packages

## Monorepo map

| Path | Role |
|---|---|
| `apps/api` | Only backend |
| `apps/user-h5` | Primary client (Vue3+TS) |
| `apps/mini-program` | Scaffold only until tasked |
| `apps/admin-h5` | Deferred |
| `packages/sdk` | Multi-platform HTTP client |
| `packages/types` | Shared TS types |
| `packages/utils` | Pure helpers |
| `packages/ui` | Design tokens |
| Root HTML / `server.py` | Legacy — do not extend |

## Feature flow (mandatory when adding a feature)

```
API route + handler
  → service
  → repository (if persistence)
  → migration (if schema change)
  → SDK / types update
  → UI page or component
  → test for money/scoring/auth paths
  → OpenAPI touch if public API changed
  → self-review
```

Missing migration or skipping service layer = incomplete.