How lumitech-co/lumitech-node-fastify-template works
Project type and purpose
• This is a back-end application template (not full-stack), designed to bootstrap production-ready REST APIs in Node.js using Fastify.
• It provides built-in support for Swagger docs, Docker, Prisma/ PostgreSQL, dependency injection (Awilix), validation (Zod), and code-generation CLIs for modules and repositories.
File structure
• Top-level:
• cli/ – code generators for modules & repositories
• src/ – main application code
• test/ – unit and integration tests
• Dockerfile & docker-compose.yml – container orchestration
• GitHub workflows, linting, commit hooks
• Under src/:
• plugins/ – Fastify plugins (DI, CORS, JWT, Swagger, Zod, error handling, env, Prisma)
• lib/ – abstracted third-party services & helpers (hashing, Awilix config, validation schemas)
• database/ – Prisma schema, migrations, generic repository generator + custom repositories
• modules/ – feature modules (routes → handlers → services → utilities)
• types/ – global TS types & DI container types
• server.ts & index.ts – Fastify server bootstrap
• Patterns: layered modular architecture, repository pattern, DI container, plugin-based extension.
README for additional insights
• Stack: TypeScript, Fastify, Zod, Swagger, Awilix, Prisma, PostgreSQL, Vitest
• Architectural highlights:
• Dependency Injection via Awilix plugin
• Swagger auto-docs from route schemas
• Prisma ORM + generic repository generator
• Docker Compose network for isolation
• Conventional commits, pre-commit hooks
a. Main components
1. Client / API Consumer (e.g., Postman, frontend, CURL)
2. Fastify HTTP Server
– Core server instance (server.ts)
– Plugin layer:
• env loader → cors → jwt auth → prisma client → awilix DI → validation (Zod) → swagger docs → error handler
3. DI Container (Awilix)
– Registers: log, config, emailService, prismaClient, repositories, services, handlers
4. Application Modules
– Routes (message.route.ts)
– Handlers (message.handler.ts)
– Services (message.service.ts + message.util.ts)
5. Data Access Layer
– Generic repository generator (generate.repository.ts)
– Custom repositories (message.repository.ts)
6. Database
– Prisma Client ↔ PostgreSQL container
7. CLI Tools (module-gen, repository-gen)
8. Testing Harness
– Vitest unit & integration tests
– Docker Compose test environment
b. Relationships & data flows
• Request flow: Client → Fastify HTTP Server → Plugin chain → Route matching → Handler → Service → Repository → Prisma → PostgreSQL → back up chain → Client
• DI resolution: Server bootstrap → Awilix plugin instantiates & wires dependencies for handlers/services/repos
• Swagger: Plugin extracts schemas from routes to generate /docs endpoint
• CLI: Standalone node scripts invoked outside of runtime to scaffold new modules/repositories
• Test flows: Tests spin up in-memory or containerized DB, boot Fastify + DI and hit services or endpoints directly.
c. Architectural patterns & principles
• Layered architecture: transport → application → domain → persistence
• Dependency Injection (Inversion of Control)
• Repository pattern with generic CRUD generator
• Plugin-based extension (Fastify)
• Modular code-gen for consistency and DRY
d. Key technologies & frameworks
• Node.js + TypeScript
• Fastify & Fastify plugins
• Awilix DI
• Prisma ORM → PostgreSQL
• Zod validation
• Swagger (fastify-swagger)
• Docker & Docker Compose
• Vitest & Docker for testing
Detail-level advice
• Layer in a swim-lane or stacked fashion.
• A section for “External Services/Utilities” (e.g., email provider in lib, future Redis, etc.).