How adrianhajdin/acquisitions works
This repository is a production-oriented Node.js API built with Express, organized as a layered backend rather than a monolith of route handlers. The main application code lives under src/, and the supporting delivery/ops assets sit at the repo root: Dockerfiles, Compose files, Drizzle migrations, GitHub Actions workflows, and test/coverage output.
The runtime entrypoint chain is src/index.js → src/server.js → src/app.js. In practice, app.js assembles the Express application, server.js likely starts the HTTP listener, and index.js serves as the top-level bootstrap. This separation makes it easy to test the app without binding a port and to run the server differently in local/dev/prod environments.
The request pipeline is split into clear layers:
• src/routes/ defines URL boundaries for auth and users.
• src/controllers/ handles HTTP input/output and delegates business logic.
• src/services/ contains the domain logic for auth and user operations.
• src/models/ contains the database model/schema layer.
• src/validations/ defines request-shape validation.
This is a classic controller/service/data-access structure, which should map cleanly to an architecture diagram.
The codebase currently exposes two explicit domains: auth and users. That suggests the primary API surface is identity and account management, with auth routes/controllers/services handling login/signup/signout flows and users routes/controllers/services handling user CRUD or profile operations.
Persistence is based on PostgreSQL through Drizzle ORM. The presence of drizzle.config.js and the drizzle/ migration folder indicates schema-first or migration-driven database management. src/config/database.js is the application’s database boundary, where the runtime connection is established and handed to the rest of the service layer.
Authentication is JWT-based, with helper functions under src/utils/jwt.js and cookie helpers under src/utils/cookies.js. That implies tokens are likely issued at auth time and then transported in HTTP cookies or headers, with middleware enforcing session state on protected routes.
Security is handled as a first-class cross-cutting concern. src/config/arcjet.js integrates Arcjet, and src/middleware/security.middleware.js likely applies request protections such as rate limiting, bot/abuse checks, or other security rules. src/middleware/auth.middleware.js guards protected endpoints and implements authorization checks, probably including role-based access control hinted at in the README.
Validation is enforced at the edge of the API using Zod schemas in src/validations/. This means request bodies are checked before they reach the service layer, preventing invalid input from contaminating business logic or database code. It also creates a clean contract between HTTP handlers and the rest of the system.
Shared utility code is intentionally small and focused. src/utils/format.js likely standardizes API responses or data formatting, while the cookie and JWT utilities centralize session/token handling. This keeps repetitive HTTP concerns out of controllers and services.
Observability is handled with src/config/logger.js, and the repo includes log artifacts under logs/. That indicates structured application logging is part of the runtime design, with logging configuration separated from request handling so it can be reused across modules and environments.
Operationally, the app is designed for containerized deployment. There are development and production Docker Compose files, a Dockerfile, and scripts in scripts/ for dev/prod workflows. The README also references Kubernetes, so the container boundary is likely the unit of deployment, with external orchestration expected in production.
The repo includes CI/CD automation under .github/workflows/ for tests, lint/format, and Docker build/push. That means quality gates are enforced before publishing images, and the repository is set up to support repeatable build and release pipelines.
Testing is centered on Jest, with tests/app.test.js and SuperTest-style API testing implied by the README. The presence of coverage output suggests the app is tested at the HTTP layer, which is appropriate for verifying route wiring, middleware behavior, and authentication flows end to end.
Main entry points: app.js Express App · auth.service.js Auth Service · auth.controller.js Auth Controller · users.controller.js Users Controller
Components 24
Application
Runtime code under src/
- Entry · Top-level application bootstrap
src/index.js - Server · Starts the HTTP listener
src/server.js - Express App · Assembles middleware and routes
src/app.js - Auth Routes · Auth endpoint boundaries
src/routes/auth.routes.js - Users Routes · User endpoint boundaries
src/routes/users.routes.js - Auth Controller · Handles auth request/response
src/controllers/auth.controller.js - Users Controller · Handles user request/response
src/controllers/users.controller.js - Auth Service · Auth business logic
src/services/auth.service.js - Users Service · User business logic
src/services/users.service.js - User Model · User schema and persistence model
src/models/user.model.js - Auth Validation · Auth request validation
src/validations/auth.validation.js - Users Validation · User request validation
src/validations/users.validation.js - Auth Middleware · Protects authenticated routes
src/middleware/auth.middleware.js - Security Middleware · Applies request protections
src/middleware/security.middleware.js - Database Config · Database connection setup
src/config/database.js - Arcjet Config · Arcjet request protection setup
src/config/arcjet.js - Logger Config · Application logging setup
src/config/logger.js - JWT Utils · Token encode/decode helpers
src/utils/jwt.js - Cookie Utils · Cookie handling helpers
src/utils/cookies.js - Format Utils · Shared formatting helpers
src/utils/format.js
Operations
Deployment, database, and CI assets
- Migrations · Drizzle migration history
drizzle/0000_happy_bedlam.sql - CI Workflows · Test, lint, and build pipelines
.github/workflows/tests.yml - Containers · Docker and compose deployment assets
Dockerfile
Connections 26
- Entry → Server: boots · Bootstrap hands off to server startup
- Server → Express App: creates · Server starts from the Express app
- Express App → Auth Routes: mounts · App registers auth routes
- Express App → Users Routes: mounts · App registers user routes
- Express App → Security Middleware: applies · Global security protections in the request pipeline
- Express App → Logger Config: uses · App/server logging configuration
- Auth Routes → Auth Controller: dispatches · Auth routes hand requests to controller handlers
- Users Routes → Users Controller: dispatches · User routes hand requests to controller handlers
- Auth Controller → Auth Validation: validates · Auth controller checks request shape at the edge
- Users Controller → Users Validation: validates · Users controller checks request shape at the edge
- Auth Controller → Auth Service: delegates · Controller passes auth work to the service layer
- Users Controller → Users Service: delegates · Controller passes user work to the service layer
- Auth Service → Database Config: reads/writes · Auth service reaches the database boundary
- Users Service → Database Config: reads/writes · Users service reaches the database boundary
- Users Service → User Model: uses · User service operates on the user model
- Auth Service → User Model: uses · Auth service may load or update user records
- Auth Service → JWT Utils: issues · Auth service creates and verifies tokens
- Auth Service → Cookie Utils: sets · Auth service stores session tokens in cookies
- Auth Controller → Format Utils: formats · Controllers standardize API responses
- Users Controller → Format Utils: formats · Controllers standardize API responses
- Auth Middleware → JWT Utils: verifies · Auth middleware validates bearer/session tokens
- Auth Middleware → Database Config: checks · Auth middleware may load session/user state
- Security Middleware → Arcjet Config: configures · Security middleware is backed by Arcjet rules
- Database Config → Migrations: aligned with · Runtime database boundary follows migration schema
- CI Workflows → API Tests: runs · CI executes the test suite
- CI Workflows → Containers: builds · CI builds and publishes container artifacts