Folder Structure¶

Where code lives in dichit-backend and the rules for adding new files.

`src/` layers¶

Path	Contents
`src/domain/`	Entities (`src/domain/entities/...`) and domain helpers
`src/application/`	Use cases, services, queue processors, dependency contracts
`src/application/interfaces/`	Repository/service contracts consumed by use cases
`src/application/use-cases/`	One folder per feature (`users/`, `auctions/`, `programs/`…)
`src/application/queue/`	Queue processors, services, interfaces
`src/infrastructure/`	Framework integrations: `db/`, `auth/`, `cache/`, `queue/`, `aws/`, `mail/`, `sms/`, `firebase/`, `config/`, `logger/`, `websocket/`, `pg/`
`src/infrastructure/db/postgres/repositories/`	Prisma/raw-SQL repositories
`src/interfaces/`	`server.ts`, `app.ts`, `http/`, `websocket/`, `utils/`, `shutdown.ts`
`src/interfaces/http/routes/`	`platform/`, `v1/`, `v2/`, `v3/`, `common/`
`src/shared/`	`constants/`, `errors/`, `swagger-schemas/`, `zod-schemas/`, `types/`, `utils/`
`src/generated/prisma/`	Generated Prisma client (do not edit)

Feature conventions¶

For a new feature (e.g. challenges), the pattern is:

src/application/use-cases/challenges/     # commands/queries + DTOs + helpers
src/application/interfaces/...            # any new contracts
src/domain/entities/challenges/           # matching domain entities
src/interfaces/http/routes/v2/...         # thin route handlers
src/infrastructure/...                    # concrete implementations
tests/...                                 # functional tests
docs/api/rest/challenges.md               # documentation (this repo!)

Use case file rules (from AGENTS.md)¶

Command DTOs live beside the command use case: *-command-dto.ts.
Query DTOs beside the query use case: *-query-dto.ts.
Use-case-specific helpers beside the owning command/query: *-helper.ts.
Share helpers at feature level only when genuinely reused.

Domain entity rules¶

New Prisma model → matching domain entity under src/domain/entities/.
Multiple related models → a folder (e.g. src/domain/entities/challenges/).
Prefer type exports for simple data shapes unless the nearby pattern uses classes.
Export from the feature index.ts and src/domain/entities/index.ts.
Repositories use domain entities for persistent model shapes; don't duplicate them as DTOs.

Route versions¶

v1 — older route modules.
v2 — web app routes (file-system autoloaded, dynamic folders use [param]).
v3 — mobile app routes.
platform/ — /health, /meta, /sentry.
webhooks/ — pg/zwitch, sentry, whatsapp.

If unsure¶

Prefer application/. Ask before broad refactors — the smallest safe change is the goal (see change-management in AGENTS.md).