# Coding Standards

## Folder Conventions

```
backend/<service>/app/
  api/v1/          # routers
  core/            # config, db, security
  models/
  schemas/         # Pydantic DTOs
  services/        # business logic
  repositories/
  middlewares/
  workers/
  tests/

frontend/
  app/             # Next.js App Router pages
  components/
  hooks/
  lib/             # API clients, auth, theme
  styles/
  public/
```

## Naming

| Kind | Convention |
| --- | --- |
| Files / modules | `snake_case.py`, `PascalCase.tsx` for components |
| Classes | `PascalCase` |
| Functions / vars | `snake_case` (Python), `camelCase` (TS) |
| DB tables / columns | `snake_case` |
| API paths | `/api/v1/...` kebab or resource nouns |
| Events | `aggregate.past_tense` |
| Feature keys | `{service}.{resource}.{action}` |
| Migrations | Alembic revision with descriptive message |

Names are English. Comments may be Persian or English.

## Python

- Python 3.11+
- Type hints on public functions
- Explicit imports; no wildcard imports
- Raise shared exceptions (`shared.exceptions`) with stable error codes

## FastAPI

- Versioned routers under `api/v1`
- Dependencies for auth and tenant
- Pydantic schemas for request/response — no ORM models in responses
- Keep route functions thin

## Django

Not used for new services. If legacy Django appears, do not expand it; prefer FastAPI services.

## DTO / Schema Conventions

- `Create`, `Update`, `Read`, `List` suffixes
- Never expose internal secrets or password hashes
- Paginated lists use shared `Page` meta

## Repository Conventions

- Accept `tenant_id` for tenant-owned entities
- No entitlement or workflow decisions
- Return domain models / rows; services map to DTOs

## Service Conventions

- One primary service per aggregate/use-case group
- Write outbox events in the same transaction as state changes
- Call other services only via HTTP clients / events

## Migration Conventions

- Autogenerate then review
- Idempotent seeds where needed (`ON CONFLICT DO NOTHING`)
- Never edit committed production revisions; add a new revision

## Event Naming

See [event-driven-architecture.md](../architecture/event-driven-architecture.md).

## API Naming

Resource nouns, plural collections, verbs only for non-CRUD actions (`/suspend`, `/activate`, `/complete`).

## Database Naming

- UUID primary keys named `id`
- Foreign keys `{table_singular}_id`
- Enums stored as string enums with documented values

## Related Documents

- [Project Principles](project-principles.md)
- [Developer Guide](developer-guide.md)
- [Service Architecture](../architecture/service-architecture.md)