layered-architecture

Summary

Every server request passes through four layers in one direction: GraphQL resolver → service → repository → Prisma.

Why it matters

The API is code-generated in both directions — GraphQL types from packages/gql, database types from Prisma — and the two type systems must never leak into each other. The service is the only layer that sees both, so it is the only place a conversion can go wrong.

Implications

• Resolvers are entry points: input validation and delegation. They carry the guards (@UseGuards(AuthGuard, ScopeGuard)) and call services only.
• Services hold business logic and convert GraphQL ↔ Prisma types. They extend AbstractBaseService, which applies society filtering, soft-delete filtering and created-by / updated-by stamping.
• Repositories speak Prisma types only and extend AbstractRepository.
• No layer calls the database directly except a repository.
• Domains live at apps/server/src/api/{domain}/, flat feature folders inside. Today: communication, finance, geography, health, plan, society, subscription-plan, upload, users, visitor.
• Generated types are imported, never hand-written: gql/server on the server, gql/client in the apps.

Related

• 2026-10-04-field-resolvers-live-with-their-service — the placement rule that follows from this
• society-scope — what the service base class filters by
• soft-delete

Sources

• AGENTS.md — "Core architecture principles"
• apps/server/src/api