5c6a2e78cf
Register all active platform services and base features in core DB so admin can manage them, add delivery/hospitality/sports-center backend phases, update apps catalog and production deploy tooling. Co-authored-by: Cursor <cursoragent@cursor.com>
113 lines
3.4 KiB
Markdown
113 lines
3.4 KiB
Markdown
# Coding Standards
|
|
|
|
## Folder Conventions
|
|
|
|
```
|
|
backend/<service>/app/
|
|
api/v1/ # routers
|
|
core/ # config, db, security
|
|
models/
|
|
schemas/ # Pydantic DTOs
|
|
services/ # business logic
|
|
commands/ # state-changing use cases (preferred for new work)
|
|
queries/ # read use cases (preferred for new work)
|
|
policies/ # authz / domain policies
|
|
specifications/ # reusable predicates
|
|
repositories/
|
|
providers/ # owning-service adapters only
|
|
validators/
|
|
events/
|
|
permissions/
|
|
middlewares/
|
|
workers/
|
|
tests/
|
|
|
|
frontend/
|
|
app/ # Next.js App Router pages
|
|
components/
|
|
hooks/
|
|
lib/ # API clients, auth, theme
|
|
styles/
|
|
public/
|
|
```
|
|
|
|
Enterprise layer expectations: [ai-framework/mandatory-phase-artifacts.md](../ai-framework/mandatory-phase-artifacts.md), [ai-framework/service-layer-template.md](../ai-framework/service-layer-template.md). Existing services may use equivalent patterns without a forced layout retrofit.
|
|
## 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)
|
|
- [Enterprise / AI Development Framework](../ai-framework/README.md)
|
|
- [Service Layer Template](../ai-framework/service-layer-template.md)
|