https://github.com/gmartins-dev/hexagonal-nestjs
hexagonal arch study
https://github.com/gmartins-dev/hexagonal-nestjs
Last synced: about 2 months ago
JSON representation
hexagonal arch study
- Host: GitHub
- URL: https://github.com/gmartins-dev/hexagonal-nestjs
- Owner: gmartins-dev
- Created: 2026-04-12T16:50:57.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-12T21:12:51.000Z (3 months ago)
- Last Synced: 2026-04-12T21:23:44.513Z (3 months ago)
- Language: TypeScript
- Size: 222 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Security: docs/SECURITY_REFERENCE.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# AssetPilot
`AssetPilot` is a backend-first fintech study project for asset financing. It is intentionally being built as a production-grade NestJS system so the repository can be used to practice real backend and fullstack engineering decisions, not just assemble a demo.
## Purpose
The project has two explicit purposes:
- study and apply hexagonal architecture, separation of concerns, SOLID-oriented design, and DDD-lite domain modeling in a realistic codebase
- prepare for a Senior Fullstack Developer role at the Bamaq Group by practicing the kinds of API, security, data, observability, testing, and operational concerns that role demands
In practical terms, AssetPilot is where the following capabilities should be exercised on purpose:
- RESTful APIs with Node.js, NestJS, PostgreSQL, and Prisma
- JWT-based authentication and RBAC
- financial correctness through idempotency, explicit ACID transactions, auditability, and immutable records
- structured logging, testing, documentation, and production-minded operational safeguards
- LGPD-minded data protection and careful handling of sensitive data
- backend contracts that can later support a data-first financial dashboard frontend without pretending that frontend already exists today
## Current State
Phase 0 foundation is the active implementation baseline:
- hexagonal project structure is in place under `src/app`, `src/modules`, and `src/shared`
- bootstrap wiring covers validated environment loading, global DTO validation, and normalized HTTP error handling
- a lightweight `GET /health` endpoint is available
- baseline Prisma schema exists for upcoming auth, contract, payment, audit, and idempotency work
- Prisma 7 is configured through `prisma.config.ts` and a PostgreSQL driver adapter at runtime
The implementation contract still lives in `docs/` and remains the source of truth for the next phases.
## Architecture And Delivery
- modular monolith with hexagonal architecture
- SOLID-oriented design, especially single responsibility and dependency inversion
- DDD-lite rather than full DDD ceremony
- backend-first implementation with future dashboard consumers in mind
- spec-driven development with AI-assisted workflow
- `pnpm` for dependency management
## Start Here
Read these files in order before implementing a feature:
1. `AGENTS.md`
2. `docs/README.md`
3. `docs/AI_CONTEXT.md`
4. `docs/ARCHITECTURE.md`
5. `docs/CODING_STANDARDS.md`
6. `docs/CODEX_PROMPTS.md`
7. `docs/SDD_WORKFLOW.md`
8. `docs/REVIEW_CHECKLIST.md`
9. `docs/IMPLEMENTATION_ROADMAP.md`
10. `docs/SPEC_TEMPLATE.md`
11. the target spec in `docs/SPECS/`
## Roadmap
1. Phase 0: Foundation
2. Phase 1: Auth and RBAC
3. Phase 2: Asset financing contracts
4. Phase 3: Payments and idempotency
5. Phase 4: Auditability and observability
6. Phase 5: Operational hardening
See `docs/IMPLEMENTATION_ROADMAP.md` and `docs/SPECS/` for the detailed execution order.
## Local Setup
1. Copy `.env.example` to `.env`.
2. Install dependencies with `pnpm install`.
3. Generate the Prisma client with `pnpm prisma:generate`.
4. Start the app with `pnpm start:dev`.
Current required environment variables:
- `NODE_ENV`
- `PORT`
- `DATABASE_URL`
Prisma notes:
- `prisma/schema.prisma` defines the data model only.
- `prisma.config.ts` provides the Prisma 7 datasource configuration.
- Nest runtime access uses `@prisma/adapter-pg` in the Prisma service.