# adrianhajdin/acquisitions architecture

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

- Interactive diagram: https://gitdiagram.com/adrianhajdin/acquisitions
- Repository: https://github.com/adrianhajdin/acquisitions

## Overview

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: [`src/app.js`](https://github.com/adrianhajdin/acquisitions/blob/main/src/app.js) (Express App), [`src/services/auth.service.js`](https://github.com/adrianhajdin/acquisitions/blob/main/src/services/auth.service.js) (Auth Service), [`src/controllers/auth.controller.js`](https://github.com/adrianhajdin/acquisitions/blob/main/src/controllers/auth.controller.js) (Auth Controller), [`src/controllers/users.controller.js`](https://github.com/adrianhajdin/acquisitions/blob/main/src/controllers/users.controller.js) (Users Controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_src["Application"]
  node_src_index(("Entry<br/>bootstrap<br/>[index.js]"))
  node_src_server["Server<br/>http start<br/>[server.js]"]
  node_src_app["Express App<br/>[app.js]"]
  node_route_auth["Auth Routes<br/>route layer<br/>[auth.routes.js]"]
  node_route_users["Users Routes<br/>route layer<br/>[users.routes.js]"]
  node_ctrl_auth["Auth Controller<br/>http controller<br/>[auth.controller.js]"]
  node_ctrl_users["Users Controller<br/>http controller"]
  node_svc_auth["Auth Service<br/>domain service<br/>[auth.service.js]"]
  node_svc_users["Users Service<br/>domain service<br/>[users.service.js]"]
  node_model_user[("User Model<br/>db model<br/>[user.model.js]")]
  node_val_auth["Auth Validation<br/>zod schemas<br/>[auth.validation.js]"]
  node_val_users["Users Validation<br/>zod schemas"]
  node_mw_auth{{"Auth Middleware<br/>auth guard<br/>[auth.middleware.js]"}}
  node_mw_security{{"Security Middleware<br/>security guard"}}
  node_cfg_db[("Database Config<br/>db boundary<br/>[database.js]")]
  node_cfg_arcjet["Arcjet Config<br/>security config<br/>[arcjet.js]"]
  node_cfg_logger["Logger Config<br/>logging config<br/>[logger.js]"]
  node_util_jwt["JWT Utils<br/>token helpers<br/>[jwt.js]"]
  node_util_cookies["Cookie Utils<br/>session helpers<br/>[cookies.js]"]
  node_util_format["Format Utils<br/>response helpers<br/>[format.js]"]
end

subgraph group_ops["Operations"]
  node_drizzle_migrations["Migrations"]
  node_ci_workflows["CI Workflows<br/>automation<br/>[tests.yml]"]
  node_docker_setup["Containers<br/>deployment assets"]
end

subgraph group_quality["Quality"]
  node_jest_tests["API Tests<br/>test suite<br/>[app.test.js]"]
end

node_src_index -->|"boots"| node_src_server
node_src_server -->|"creates"| node_src_app
node_src_app -->|"mounts"| node_route_auth
node_src_app -->|"mounts"| node_route_users
node_src_app -->|"applies"| node_mw_security
node_src_app -->|"uses"| node_cfg_logger
node_route_auth -->|"dispatches"| node_ctrl_auth
node_route_users -->|"dispatches"| node_ctrl_users
node_ctrl_auth -->|"validates"| node_val_auth
node_ctrl_users -->|"validates"| node_val_users
node_ctrl_auth -->|"delegates"| node_svc_auth
node_ctrl_users -->|"delegates"| node_svc_users
node_svc_auth -->|"reads/writes"| node_cfg_db
node_svc_users -->|"reads/writes"| node_cfg_db
node_svc_users -->|"uses"| node_model_user
node_svc_auth -->|"uses"| node_model_user
node_svc_auth -->|"issues"| node_util_jwt
node_svc_auth -->|"sets"| node_util_cookies
node_ctrl_auth -->|"formats"| node_util_format
node_ctrl_users -->|"formats"| node_util_format
node_mw_auth -->|"verifies"| node_util_jwt
node_mw_auth -->|"checks"| node_cfg_db
node_mw_security -->|"configures"| node_cfg_arcjet
node_cfg_db -.->|"aligned with"| node_drizzle_migrations
node_ci_workflows -->|"runs"| node_jest_tests
node_ci_workflows -->|"builds"| node_docker_setup

click node_src_index "https://github.com/adrianhajdin/acquisitions/blob/main/src/index.js"
click node_src_server "https://github.com/adrianhajdin/acquisitions/blob/main/src/server.js"
click node_src_app "https://github.com/adrianhajdin/acquisitions/blob/main/src/app.js"
click node_route_auth "https://github.com/adrianhajdin/acquisitions/blob/main/src/routes/auth.routes.js"
click node_route_users "https://github.com/adrianhajdin/acquisitions/blob/main/src/routes/users.routes.js"
click node_ctrl_auth "https://github.com/adrianhajdin/acquisitions/blob/main/src/controllers/auth.controller.js"
click node_ctrl_users "https://github.com/adrianhajdin/acquisitions/blob/main/src/controllers/users.controller.js"
click node_svc_auth "https://github.com/adrianhajdin/acquisitions/blob/main/src/services/auth.service.js"
click node_svc_users "https://github.com/adrianhajdin/acquisitions/blob/main/src/services/users.service.js"
click node_model_user "https://github.com/adrianhajdin/acquisitions/blob/main/src/models/user.model.js"
click node_val_auth "https://github.com/adrianhajdin/acquisitions/blob/main/src/validations/auth.validation.js"
click node_val_users "https://github.com/adrianhajdin/acquisitions/blob/main/src/validations/users.validation.js"
click node_mw_auth "https://github.com/adrianhajdin/acquisitions/blob/main/src/middleware/auth.middleware.js"
click node_mw_security "https://github.com/adrianhajdin/acquisitions/blob/main/src/middleware/security.middleware.js"
click node_cfg_db "https://github.com/adrianhajdin/acquisitions/blob/main/src/config/database.js"
click node_cfg_arcjet "https://github.com/adrianhajdin/acquisitions/blob/main/src/config/arcjet.js"
click node_cfg_logger "https://github.com/adrianhajdin/acquisitions/blob/main/src/config/logger.js"
click node_util_jwt "https://github.com/adrianhajdin/acquisitions/blob/main/src/utils/jwt.js"
click node_util_cookies "https://github.com/adrianhajdin/acquisitions/blob/main/src/utils/cookies.js"
click node_util_format "https://github.com/adrianhajdin/acquisitions/blob/main/src/utils/format.js"
click node_drizzle_migrations "https://github.com/adrianhajdin/acquisitions/blob/main/drizzle/0000_happy_bedlam.sql"
click node_ci_workflows "https://github.com/adrianhajdin/acquisitions/blob/main/.github/workflows/tests.yml"
click node_docker_setup "https://github.com/adrianhajdin/acquisitions/tree/main/Dockerfile"
click node_jest_tests "https://github.com/adrianhajdin/acquisitions/blob/main/tests/app.test.js"

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_src_index,node_src_server,node_src_app,node_route_auth,node_route_users,node_ctrl_auth,node_ctrl_users,node_svc_auth,node_svc_users,node_model_user,node_val_auth,node_val_users,node_mw_auth,node_mw_security,node_cfg_db,node_cfg_arcjet,node_cfg_logger,node_util_jwt,node_util_cookies,node_util_format toneBlue
class node_drizzle_migrations,node_ci_workflows,node_docker_setup toneAmber
class node_jest_tests toneMint
```

## Components

### Application

Runtime code under src/

- [Entry](https://github.com/adrianhajdin/acquisitions/blob/main/src/index.js): bootstrap · Top-level application bootstrap · `src/index.js`
- [Server](https://github.com/adrianhajdin/acquisitions/blob/main/src/server.js): http start · Starts the HTTP listener · `src/server.js`
- [Express App](https://github.com/adrianhajdin/acquisitions/blob/main/src/app.js): express app · Assembles middleware and routes · `src/app.js`
- [Auth Routes](https://github.com/adrianhajdin/acquisitions/blob/main/src/routes/auth.routes.js): route layer · Auth endpoint boundaries · `src/routes/auth.routes.js`
- [Users Routes](https://github.com/adrianhajdin/acquisitions/blob/main/src/routes/users.routes.js): route layer · User endpoint boundaries · `src/routes/users.routes.js`
- [Auth Controller](https://github.com/adrianhajdin/acquisitions/blob/main/src/controllers/auth.controller.js): http controller · Handles auth request/response · `src/controllers/auth.controller.js`
- [Users Controller](https://github.com/adrianhajdin/acquisitions/blob/main/src/controllers/users.controller.js): http controller · Handles user request/response · `src/controllers/users.controller.js`
- [Auth Service](https://github.com/adrianhajdin/acquisitions/blob/main/src/services/auth.service.js): domain service · Auth business logic · `src/services/auth.service.js`
- [Users Service](https://github.com/adrianhajdin/acquisitions/blob/main/src/services/users.service.js): domain service · User business logic · `src/services/users.service.js`
- [User Model](https://github.com/adrianhajdin/acquisitions/blob/main/src/models/user.model.js): db model · User schema and persistence model · `src/models/user.model.js`
- [Auth Validation](https://github.com/adrianhajdin/acquisitions/blob/main/src/validations/auth.validation.js): zod schemas · Auth request validation · `src/validations/auth.validation.js`
- [Users Validation](https://github.com/adrianhajdin/acquisitions/blob/main/src/validations/users.validation.js): zod schemas · User request validation · `src/validations/users.validation.js`
- [Auth Middleware](https://github.com/adrianhajdin/acquisitions/blob/main/src/middleware/auth.middleware.js): auth guard · Protects authenticated routes · `src/middleware/auth.middleware.js`
- [Security Middleware](https://github.com/adrianhajdin/acquisitions/blob/main/src/middleware/security.middleware.js): security guard · Applies request protections · `src/middleware/security.middleware.js`
- [Database Config](https://github.com/adrianhajdin/acquisitions/blob/main/src/config/database.js): db boundary · Database connection setup · `src/config/database.js`
- [Arcjet Config](https://github.com/adrianhajdin/acquisitions/blob/main/src/config/arcjet.js): security config · Arcjet request protection setup · `src/config/arcjet.js`
- [Logger Config](https://github.com/adrianhajdin/acquisitions/blob/main/src/config/logger.js): logging config · Application logging setup · `src/config/logger.js`
- [JWT Utils](https://github.com/adrianhajdin/acquisitions/blob/main/src/utils/jwt.js): token helpers · Token encode/decode helpers · `src/utils/jwt.js`
- [Cookie Utils](https://github.com/adrianhajdin/acquisitions/blob/main/src/utils/cookies.js): session helpers · Cookie handling helpers · `src/utils/cookies.js`
- [Format Utils](https://github.com/adrianhajdin/acquisitions/blob/main/src/utils/format.js): response helpers · Shared formatting helpers · `src/utils/format.js`

### Operations

Deployment, database, and CI assets

- [Migrations](https://github.com/adrianhajdin/acquisitions/blob/main/drizzle/0000_happy_bedlam.sql): schema migrations · Drizzle migration history · `drizzle/0000_happy_bedlam.sql`
- [CI Workflows](https://github.com/adrianhajdin/acquisitions/blob/main/.github/workflows/tests.yml): automation · Test, lint, and build pipelines · `.github/workflows/tests.yml`
- [Containers](https://github.com/adrianhajdin/acquisitions/tree/main/Dockerfile): deployment assets · Docker and compose deployment assets · `Dockerfile`

### Quality

Tests and generated coverage

- [API Tests](https://github.com/adrianhajdin/acquisitions/blob/main/tests/app.test.js): test suite · HTTP-level Jest/SuperTest coverage · `tests/app.test.js`

## Connections

- 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