# Service Architecture

## Internal Layering (every backend service)

```
API (routers)  →  Services (business logic)  →  Repositories  →  Models (DB)
                         ↑
                     Schemas (Pydantic DTOs)
```

| Layer | Allowed | Forbidden |
| --- | --- | --- |
| API / Views | Auth deps, validation, HTTP mapping | Business rules, raw SQL |
| Services | Domain logic, orchestration, events | HTTP concerns, UI |
| Repositories | Queries/persistence | Business decisions |
| Models | Schema mapping | Business workflows |

## Core Package Layout

- `core/` — config, database, cache, security, logging
- `middlewares/` — tenant resolution
- `workers/` — Celery tasks (outbox, SSL provision, …)
- `api/v1/` — versioned routers
- `tests/` — automated tests

## Adding a Service

1. New folder under `backend/services/<name>/`
2. Independent database + Alembic
3. Register in Core service/module registry
4. Document in [module-registry.md](../module-registry.md)
5. UI only in `frontend/`, API-only access
6. Follow [coding-standards.md](../development/coding-standards.md)

## Related Documents

- [Module Boundaries](module-boundaries.md)
- [Developer Guide](../development/developer-guide.md)
- [Project Principles](../development/project-principles.md)