How notiz-dev/nestjs-prisma-starter works
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: app.module.ts App module · auth.module.ts Auth module · schema.prisma Prisma schema · posts.resolver.ts Posts resolver
Components 24
Nest runtime
Application bootstrap and module composition
- Main · Starts the Nest application
src/main.ts - App module · Wires the application modules
src/app.module.ts - Root resolver · Top-level GraphQL entry points
src/app.resolver.ts - Root service · Shared application-level logic
src/app.service.ts
Feature modules
GraphQL domain boundaries
- Auth module · JWT-based authentication feature
src/auth/auth.module.ts - Auth resolver · Handles signup, login, and token flows
src/auth/auth.resolver.ts - Auth service · Issues tokens and verifies credentials
src/auth/auth.service.ts - JWT strategy · Validates bearer tokens for requests
src/auth/jwt.strategy.ts - GQL guard · Protects authenticated GraphQL fields
src/auth/gql-auth.guard.ts - Users module · User profile and password management
src/users/users.module.ts - Users resolver · Exposes user profile operations
src/users/users.resolver.ts - Users service · Handles user profile business logic
src/users/users.service.ts - Posts module · Post queries and mutations
src/posts/posts.module.ts - Posts resolver · Exposes post list and mutation operations
src/posts/posts.resolver.ts
Shared core
Cross-cutting config, auth, and pagination primitives
- GQL config · GraphQL server configuration
src/gql-config.service.ts - Config · Loads runtime settings from the environment
src/common/configs/config.ts - Base model · Shared GraphQL model base types
src/common/models/base.model.ts - Pagination · Page info and pagination arguments
src/common/pagination/pagination.ts - User decorator · Extracts the current user in GraphQL resolvers
src/common/decorators/user.decorator.ts
Persistence
Prisma schema, migrations, and seed data
- Prisma schema · Database schema and migrations
prisma/schema.prisma - Migrations · Prisma migration history
prisma/migrations/20220118074231_init/migration.sql - Seed data · Initial database seeding
prisma/seed.ts
GraphQL clients
Example operations and generated contract
- Schema · Generated GraphQL API contract
src/schema.graphql - Sample ops · Example GraphQL operations
graphql/auth.graphql
Connections 29
- 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