# notiz-dev/nestjs-prisma-starter architecture

> Architecture diagram of the GitHub repository notiz-dev/nestjs-prisma-starter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/notiz-dev/nestjs-prisma-starter
- Repository: https://github.com/notiz-dev/nestjs-prisma-starter

## Overview

1. This is a NestJS backend starter built around a single Node.js application that exposes a GraphQL API and uses Prisma as its database access and migration layer. The main runtime entry is `src/main.ts`, with application wiring in `src/app.module.ts`.

2. The primary request path is GraphQL-first: clients send operations to the Nest GraphQL server, Nest routes them to resolvers, and the schema is generated from decorators and TypeScript models. The committed `src/schema.graphql` is the generated API contract, while the `graphql/*.graphql` files are example client operations.

3. The API is split into feature modules: `auth`, `users`, and `posts`, plus the root `AppResolver`/`AppService`. Each module has its own resolver and, where needed, service layer, keeping transport concerns separated from business logic.

4. Authentication is JWT-based and integrated with GraphQL. The flow is: `signup`/`login` in `AuthResolver` and `AuthService` issue tokens, `JwtStrategy` validates bearer tokens, and `GqlAuthGuard` protects GraphQL fields that require identity. The `user` decorator in `src/common/decorators/user.decorator.ts` is the boundary for pulling the current user into resolvers.

5. The persistence boundary is Prisma + PostgreSQL. `prisma/schema.prisma` defines the data model, `prisma/migrations` holds schema history, and `prisma/seed.ts` populates initial data. The app depends on `DATABASE_URL`, and the README shows Postgres as the backing database, typically run locally via Docker.

6. The domain model is centered on users and posts. `users` contains DTOs for updating profiles and changing passwords, a user service, and GraphQL models. `posts` contains post creation inputs, ID args, ordering/pagination-related types, and a connection model, suggesting list queries are paginated and sortable.

7. Shared infrastructure lives under `src/common`. This includes configuration loading, base model types, pagination helpers, and ordering abstractions. These are cross-cutting primitives used by multiple feature modules rather than business logic themselves.

8. Configuration is environment-driven. `src/common/configs` defines the config interface/loader, and the README and Docker setup rely on `.env` for database and runtime settings. That makes deployment/container behavior dependent on external environment variables rather than hard-coded values.

9. There is a clear contract between API shape and client consumption. The GraphQL schema is code-first, with inputs, models, and resolvers acting as the source of truth. Swagger is also mentioned in the README, implying the Nest app likely exposes some REST/OpenAPI documentation in addition to GraphQL, even though GraphQL is the main API surface in this repository.

10. Testing is layered around the same boundaries: unit tests for controllers/resolvers/services, and e2e tests under `test/`. This suggests the app is intended to be verified both at the resolver/service boundary and at the full application boundary.

11. Containerization and local orchestration are first-class. There are Dockerfiles for the app, Docker Compose files for the database, migrations, and full stack startup, which means the architecture is designed to be reproducible in isolated containers as well as run directly with Node/Nest tooling.

12. Tooling is standard TypeScript/Nest scaffolding: ESLint, Prettier, Nest CLI, Jest, and Prisma CLI. Those tools support schema generation, migration workflows, and CI automation, but the core architecture remains: GraphQL edge -> auth guard -> feature resolver/service -> Prisma -> PostgreSQL.

Main entry points: [`src/app.module.ts`](https://github.com/notiz-dev/nestjs-prisma-starter/blob/main/src/app.module.ts) (App module), [`src/auth/auth.module.ts`](https://github.com/notiz-dev/nestjs-prisma-starter/blob/main/src/auth/auth.module.ts) (Auth module), [`prisma/schema.prisma`](https://github.com/notiz-dev/nestjs-prisma-starter/blob/main/prisma/schema.prisma) (Prisma schema), [`src/posts/posts.resolver.ts`](https://github.com/notiz-dev/nestjs-prisma-starter/blob/main/src/posts/posts.resolver.ts) (Posts resolver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Nest runtime"]
  node_main["Main<br/>bootstrap<br/>[main.ts]"]
  node_appmodule["App module<br/>composition root<br/>[app.module.ts]"]
  node_appresolver["Root resolver<br/>graphql resolver<br/>[app.resolver.ts]"]
  node_appservice["Root service<br/>app service<br/>[app.service.ts]"]
end

subgraph group_features["Feature modules"]
  node_authmodule["Auth module<br/>feature module<br/>[auth.module.ts]"]
  node_authresolver["Auth resolver<br/>graphql resolver<br/>[auth.resolver.ts]"]
  node_authservice["Auth service<br/>domain service<br/>[auth.service.ts]"]
  node_jwtstrategy["JWT strategy<br/>auth strategy<br/>[jwt.strategy.ts]"]
  node_gqlguard["GQL guard<br/>auth guard<br/>[gql-auth.guard.ts]"]
  node_usersmodule["Users module<br/>feature module<br/>[users.module.ts]"]
  node_usersresolver["Users resolver<br/>graphql resolver<br/>[users.resolver.ts]"]
  node_usersservice["Users service<br/>domain service<br/>[users.service.ts]"]
  node_postsmodule["Posts module<br/>feature module<br/>[posts.module.ts]"]
  node_postsresolver["Posts resolver<br/>graphql resolver<br/>[posts.resolver.ts]"]
end

subgraph group_shared["Shared core"]
  node_gqlconfig["GQL config<br/>graphql setup"]
  node_config["Config<br/>[config.ts]"]
  node_commonmodels["Base model<br/>shared model<br/>[base.model.ts]"]
  node_pagination["Pagination<br/>[pagination.ts]"]
  node_userdecorator["User decorator<br/>auth helper<br/>[user.decorator.ts]"]
end

subgraph group_data["Persistence"]
  node_prismamodel[("Prisma schema<br/>data model<br/>[schema.prisma]")]
  node_prisamigrations["Migrations<br/>schema history<br/>[migration.sql]"]
  node_prismaseed["Seed data<br/>bootstrap data<br/>[seed.ts]"]
end

subgraph group_clients["GraphQL clients"]
  node_schema["Schema<br/>graphql contract<br/>[schema.graphql]"]
  node_queries["Sample ops<br/>client documents<br/>[auth.graphql]"]
end

node_main -->|"boots"| node_appmodule
node_appmodule -->|"configures"| node_gqlconfig
node_appmodule -->|"loads"| node_config
node_appmodule -->|"imports"| node_authmodule
node_appmodule -->|"imports"| node_usersmodule
node_appmodule -->|"imports"| node_postsmodule
node_appmodule -->|"exposes"| node_appresolver
node_appmodule -->|"uses"| node_appservice
node_appresolver -->|"delegates"| node_appservice
node_authmodule -->|"contains"| node_authresolver
node_authmodule -->|"contains"| node_authservice
node_authmodule -->|"uses"| node_jwtstrategy
node_authmodule -->|"uses"| node_gqlguard
node_authresolver -->|"delegates"| node_authservice
node_authresolver -->|"reads user"| node_userdecorator
node_usersmodule -->|"contains"| node_usersresolver
node_usersmodule -->|"contains"| node_usersservice
node_usersresolver -->|"delegates"| node_usersservice
node_usersresolver -->|"protects"| node_gqlguard
node_postsmodule -->|"contains"| node_postsresolver
node_postsresolver -->|"uses"| node_pagination
node_postsresolver -->|"reads user"| node_userdecorator
node_authservice -->|"persists via"| node_prismamodel
node_usersservice -->|"persists via"| node_prismamodel
node_postsresolver -->|"persists via"| node_prismamodel
node_prismamodel -->|"evolves through"| node_prisamigrations
node_prismamodel -->|"bootstrapped by"| node_prismaseed
node_appmodule -.->|"produces"| node_schema
node_schema -.->|"consumed by"| node_queries

click node_main "https://github.com/notiz-dev/nestjs-prisma-starter/blob/main/src/main.ts"
click node_appmodule "https://github.com/notiz-dev/nestjs-prisma-starter/blob/main/src/app.module.ts"
click node_gqlconfig "https://github.com/notiz-dev/nestjs-prisma-starter/blob/main/src/gql-config.service.ts"
click node_config "https://github.com/notiz-dev/nestjs-prisma-starter/blob/main/src/common/configs/config.ts"
click node_commonmodels "https://github.com/notiz-dev/nestjs-prisma-starter/blob/main/src/common/models/base.model.ts"
click node_pagination "https://github.com/notiz-dev/nestjs-prisma-starter/blob/main/src/common/pagination/pagination.ts"
click node_userdecorator "https://github.com/notiz-dev/nestjs-prisma-starter/blob/main/src/common/decorators/user.decorator.ts"
click node_authmodule "https://github.com/notiz-dev/nestjs-prisma-starter/blob/main/src/auth/auth.module.ts"
click node_authresolver "https://github.com/notiz-dev/nestjs-prisma-starter/blob/main/src/auth/auth.resolver.ts"
click node_authservice "https://github.com/notiz-dev/nestjs-prisma-starter/blob/main/src/auth/auth.service.ts"
click node_jwtstrategy "https://github.com/notiz-dev/nestjs-prisma-starter/blob/main/src/auth/jwt.strategy.ts"
click node_gqlguard "https://github.com/notiz-dev/nestjs-prisma-starter/blob/main/src/auth/gql-auth.guard.ts"
click node_usersmodule "https://github.com/notiz-dev/nestjs-prisma-starter/blob/main/src/users/users.module.ts"
click node_usersresolver "https://github.com/notiz-dev/nestjs-prisma-starter/blob/main/src/users/users.resolver.ts"
click node_usersservice "https://github.com/notiz-dev/nestjs-prisma-starter/blob/main/src/users/users.service.ts"
click node_postsmodule "https://github.com/notiz-dev/nestjs-prisma-starter/blob/main/src/posts/posts.module.ts"
click node_postsresolver "https://github.com/notiz-dev/nestjs-prisma-starter/blob/main/src/posts/posts.resolver.ts"
click node_appresolver "https://github.com/notiz-dev/nestjs-prisma-starter/blob/main/src/app.resolver.ts"
click node_appservice "https://github.com/notiz-dev/nestjs-prisma-starter/blob/main/src/app.service.ts"
click node_prismamodel "https://github.com/notiz-dev/nestjs-prisma-starter/blob/main/prisma/schema.prisma"
click node_prisamigrations "https://github.com/notiz-dev/nestjs-prisma-starter/blob/main/prisma/migrations/20220118074231_init/migration.sql"
click node_prismaseed "https://github.com/notiz-dev/nestjs-prisma-starter/blob/main/prisma/seed.ts"
click node_schema "https://github.com/notiz-dev/nestjs-prisma-starter/blob/main/src/schema.graphql"
click node_queries "https://github.com/notiz-dev/nestjs-prisma-starter/blob/main/graphql/auth.graphql"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_appmodule,node_appresolver,node_appservice toneBlue
class node_authmodule,node_authresolver,node_authservice,node_jwtstrategy,node_gqlguard,node_usersmodule,node_usersresolver,node_usersservice,node_postsmodule,node_postsresolver toneAmber
class node_gqlconfig,node_config,node_commonmodels,node_pagination,node_userdecorator toneMint
class node_prismamodel,node_prisamigrations,node_prismaseed toneRose
class node_schema,node_queries toneIndigo
```

## Components

### Nest runtime

Application bootstrap and module composition

- [Main](https://github.com/notiz-dev/nestjs-prisma-starter/blob/main/src/main.ts): bootstrap · Starts the Nest application · `src/main.ts`
- [App module](https://github.com/notiz-dev/nestjs-prisma-starter/blob/main/src/app.module.ts): composition root · Wires the application modules · `src/app.module.ts`
- [Root resolver](https://github.com/notiz-dev/nestjs-prisma-starter/blob/main/src/app.resolver.ts): graphql resolver · Top-level GraphQL entry points · `src/app.resolver.ts`
- [Root service](https://github.com/notiz-dev/nestjs-prisma-starter/blob/main/src/app.service.ts): app service · Shared application-level logic · `src/app.service.ts`

### Feature modules

GraphQL domain boundaries

- [Auth module](https://github.com/notiz-dev/nestjs-prisma-starter/blob/main/src/auth/auth.module.ts): feature module · JWT-based authentication feature · `src/auth/auth.module.ts`
- [Auth resolver](https://github.com/notiz-dev/nestjs-prisma-starter/blob/main/src/auth/auth.resolver.ts): graphql resolver · Handles signup, login, and token flows · `src/auth/auth.resolver.ts`
- [Auth service](https://github.com/notiz-dev/nestjs-prisma-starter/blob/main/src/auth/auth.service.ts): domain service · Issues tokens and verifies credentials · `src/auth/auth.service.ts`
- [JWT strategy](https://github.com/notiz-dev/nestjs-prisma-starter/blob/main/src/auth/jwt.strategy.ts): auth strategy · Validates bearer tokens for requests · `src/auth/jwt.strategy.ts`
- [GQL guard](https://github.com/notiz-dev/nestjs-prisma-starter/blob/main/src/auth/gql-auth.guard.ts): auth guard · Protects authenticated GraphQL fields · `src/auth/gql-auth.guard.ts`
- [Users module](https://github.com/notiz-dev/nestjs-prisma-starter/blob/main/src/users/users.module.ts): feature module · User profile and password management · `src/users/users.module.ts`
- [Users resolver](https://github.com/notiz-dev/nestjs-prisma-starter/blob/main/src/users/users.resolver.ts): graphql resolver · Exposes user profile operations · `src/users/users.resolver.ts`
- [Users service](https://github.com/notiz-dev/nestjs-prisma-starter/blob/main/src/users/users.service.ts): domain service · Handles user profile business logic · `src/users/users.service.ts`
- [Posts module](https://github.com/notiz-dev/nestjs-prisma-starter/blob/main/src/posts/posts.module.ts): feature module · Post queries and mutations · `src/posts/posts.module.ts`
- [Posts resolver](https://github.com/notiz-dev/nestjs-prisma-starter/blob/main/src/posts/posts.resolver.ts): graphql resolver · Exposes post list and mutation operations · `src/posts/posts.resolver.ts`

### Shared core

Cross-cutting config, auth, and pagination primitives

- [GQL config](https://github.com/notiz-dev/nestjs-prisma-starter/blob/main/src/gql-config.service.ts): graphql setup · GraphQL server configuration · `src/gql-config.service.ts`
- [Config](https://github.com/notiz-dev/nestjs-prisma-starter/blob/main/src/common/configs/config.ts): env config · Loads runtime settings from the environment · `src/common/configs/config.ts`
- [Base model](https://github.com/notiz-dev/nestjs-prisma-starter/blob/main/src/common/models/base.model.ts): shared model · Shared GraphQL model base types · `src/common/models/base.model.ts`
- [Pagination](https://github.com/notiz-dev/nestjs-prisma-starter/blob/main/src/common/pagination/pagination.ts): shared pagination · Page info and pagination arguments · `src/common/pagination/pagination.ts`
- [User decorator](https://github.com/notiz-dev/nestjs-prisma-starter/blob/main/src/common/decorators/user.decorator.ts): auth helper · Extracts the current user in GraphQL resolvers · `src/common/decorators/user.decorator.ts`

### Persistence

Prisma schema, migrations, and seed data

- [Prisma schema](https://github.com/notiz-dev/nestjs-prisma-starter/blob/main/prisma/schema.prisma): data model · Database schema and migrations · `prisma/schema.prisma`
- [Migrations](https://github.com/notiz-dev/nestjs-prisma-starter/blob/main/prisma/migrations/20220118074231_init/migration.sql): schema history · Prisma migration history · `prisma/migrations/20220118074231_init/migration.sql`
- [Seed data](https://github.com/notiz-dev/nestjs-prisma-starter/blob/main/prisma/seed.ts): bootstrap data · Initial database seeding · `prisma/seed.ts`

### GraphQL clients

Example operations and generated contract

- [Schema](https://github.com/notiz-dev/nestjs-prisma-starter/blob/main/src/schema.graphql): graphql contract · Generated GraphQL API contract · `src/schema.graphql`
- [Sample ops](https://github.com/notiz-dev/nestjs-prisma-starter/blob/main/graphql/auth.graphql): client documents · Example GraphQL operations · `graphql/auth.graphql`

## Connections

- Main → App module: boots · Application startup composes the root module
- App module → GQL config: configures · Sets up the GraphQL server
- App module → Config: loads · Reads environment-driven settings
- App module → Auth module: imports · Registers authentication feature
- App module → Users module: imports · Registers user feature
- App module → Posts module: imports · Registers post feature
- App module → Root resolver: exposes · Root GraphQL entry points
- App module → Root service: uses · Shared application service
- Root resolver → Root service: delegates · Resolver calls shared app logic
- Auth module → Auth resolver: contains · Authentication GraphQL entry points
- Auth module → Auth service: contains · Authentication business logic
- Auth module → JWT strategy: uses · Validates JWT bearer tokens
- Auth module → GQL guard: uses · Protects authenticated GraphQL fields
- Auth resolver → Auth service: delegates · Signup and login flow through the service
- Auth resolver → User decorator: reads user · Pulls current identity from GraphQL context
- Users module → Users resolver: contains · User GraphQL entry points
- Users module → Users service: contains · User business logic
- Users resolver → Users service: delegates · Profile and password operations
- Users resolver → GQL guard: protects · Authenticated user fields
- Posts module → Posts resolver: contains · Post GraphQL entry points
- Posts resolver → Pagination: uses · List queries use shared pagination primitives
- Posts resolver → User decorator: reads user · Uses current identity for scoped operations
- Auth service → Prisma schema: persists via · Application data flows through Prisma
- Users service → Prisma schema: persists via · User state is stored in PostgreSQL through Prisma
- Posts resolver → Prisma schema: persists via · Post data is backed by Prisma models
- Prisma schema → Migrations: evolves through · Schema changes are captured as migrations
- Prisma schema → Seed data: bootstrapped by · Seed script populates initial data
- App module → Schema: produces · Code-first GraphQL schema is generated from modules
- Schema → Sample ops: consumed by · Client operations target the generated contract
