# itsnaleeka/distributed-user-management-system architecture

> Architecture diagram of the GitHub repository itsnaleeka/distributed-user-management-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/itsnaleeka/distributed-user-management-system
- Repository: https://github.com/itsnaleeka/distributed-user-management-system

## Overview

1. **Overall shape**
   - This repository is a small Go monorepo for a **distributed user management system**.
   - The main runtime boundary is split into **two separate binaries**: a **gateway** and a **user-service**.

2. **Entry points / deployable units**
   - `cmd/gateway/main.go` is the startup point for the edge-facing service.
   - `cmd/user-service/main.go` is the startup point for the domain service that owns user operations.
   - These are the two top-level processes you would place as separate boxes in an architecture diagram.

3. **Request flow**
   - External clients hit the **gateway** first.
   - The gateway likely acts as the **front door / routing layer**, forwarding user-related traffic to the **user-service**.
   - The user-service is the component that should be shown as handling the actual user domain logic and persistence.

4. **Domain ownership**
   - The system’s core domain is **users**.
   - The user-service appears to own that domain end-to-end: API handling, business logic, and database access.
   - There is no evidence of additional domain services in this repo; the architecture is centered on one bounded context.

5. **Persistence layer**
   - The repo includes a dedicated `db/` area with:
     - `db/migration/0001_create_users_table.up.sql` for schema creation
     - `db/queries/users.sql` for SQL query definitions
   - This indicates a **SQL-backed relational database** with explicit migrations and query files.

6. **Generated data-access code**
   - `sqlc.yml` and `internal/db/users.sql.go` strongly suggest use of **sqlc**.
   - That means SQL is written by hand, then compiled into typed Go database access code.
   - In the diagram, this is an important internal boundary: **user-service code -> generated DB layer -> database**.

7. **Internal DB package**
   - `internal/db/db.go`, `internal/db/models.go`, and `internal/db/users.sql.go` form the data-access package.
   - `models.go` likely contains typed representations of user records.
   - This package is not a standalone service; it is a shared internal library used by the runtime services, most likely the user-service.

8. **Database lifecycle**
   - The presence of migration files means schema changes are managed separately from application startup.
   - The database is therefore a distinct infrastructure dependency, not embedded storage.
   - For an architecture diagram, show **migrations** as a build/deploy-time concern feeding the database schema, not a live runtime component.

9. **Local infrastructure / orchestration**
   - `docker-compose.yml` indicates the system can be run locally with containerized components.
   - This likely wires together the gateway, user-service, and database for development/testing.
   - If you draw an environment box, this file represents the local integration harness.

10. **Quality and workflow tooling**
   - `.githooks/commit-msg` and `.githooks/pre-commit` show repository-level commit checks.
   - `.golangci.yml` indicates static analysis/linting for Go code.
   - These affect development workflow, not runtime architecture.

11. **Suggested diagram boundaries**
   - Box 1: **Client / external caller**
   - Box 2: **Gateway service**
   - Box 3: **User-service**
   - Box 4: **Generated DB access layer (sqlc-backed internal package)**
   - Box 5: **Relational database**
   - Side flow: **SQL migrations** applied to the database
   - Side tooling: **docker-compose** for local composition, **lint/hooks** for repo hygiene

12. **What matters most**
   - The key architectural distinction is between **edge routing** and **domain ownership**.
   - The gateway exposes the system; the user-service owns user behavior and storage; sqlc-generated code bridges application logic to the SQL database.

Main entry points: [`cmd/user-service/main.go`](https://github.com/itsnaleeka/distributed-user-management-system/blob/main/cmd/user-service/main.go) (User Service), [`cmd/gateway/main.go`](https://github.com/itsnaleeka/distributed-user-management-system/blob/main/cmd/gateway/main.go) (Gateway), [`docker-compose.yml`](https://github.com/itsnaleeka/distributed-user-management-system/blob/main/docker-compose.yml) (Compose), [`internal/db/db.go`](https://github.com/itsnaleeka/distributed-user-management-system/blob/main/internal/db/db.go) (DB Package)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_external["External"]
  node_client(("Client<br/>caller"))
end

subgraph group_services["Services"]
  node_gateway["Gateway<br/>edge service<br/>[main.go]"]
  node_user_service["User Service<br/>domain service<br/>[main.go]"]
end

subgraph group_data["Data"]
  node_internal_db["DB Package<br/>internal data layer<br/>[db.go]"]
  node_sqlc_code["Generated SQL<br/>sqlc output<br/>[users.sql.go]"]
  node_db_models["Models<br/>[models.go]"]
  node_sql_queries["Queries<br/>sql definitions<br/>[users.sql]"]
  node_migrations["Migrations<br/>schema migration"]
  node_database[("Database<br/>relational store")]
end

subgraph group_workflow["Workflow"]
  node_compose["Compose<br/>local orchestration<br/>[docker-compose.yml]"]
  node_lint["Linting<br/>static analysis<br/>[.golangci.yml]"]
  node_hooks["Git Hooks<br/>commit checks<br/>[pre-commit]"]
end

node_client -->|"HTTP requests"| node_gateway
node_gateway -->|"forward"| node_user_service
node_user_service -->|"use"| node_internal_db
node_internal_db -->|"implements"| node_sqlc_code
node_internal_db -->|"maps"| node_db_models
node_sqlc_code -->|"generated from"| node_sql_queries
node_user_service -->|"persist"| node_database
node_sql_queries -->|"executes on"| node_database
node_migrations -.->|"schema changes"| node_database
node_compose -.->|"runs"| node_gateway
node_compose -.->|"runs"| node_user_service
node_compose -.->|"provisions"| node_database
node_lint -.->|"checks"| node_gateway
node_lint -.->|"checks"| node_user_service
node_hooks -.->|"enforces"| node_lint

click node_gateway "https://github.com/itsnaleeka/distributed-user-management-system/blob/main/cmd/gateway/main.go"
click node_user_service "https://github.com/itsnaleeka/distributed-user-management-system/blob/main/cmd/user-service/main.go"
click node_internal_db "https://github.com/itsnaleeka/distributed-user-management-system/blob/main/internal/db/db.go"
click node_sqlc_code "https://github.com/itsnaleeka/distributed-user-management-system/blob/main/internal/db/users.sql.go"
click node_db_models "https://github.com/itsnaleeka/distributed-user-management-system/blob/main/internal/db/models.go"
click node_sql_queries "https://github.com/itsnaleeka/distributed-user-management-system/blob/main/db/queries/users.sql"
click node_migrations "https://github.com/itsnaleeka/distributed-user-management-system/blob/main/db/migration/0001_create_users_table.up.sql"
click node_compose "https://github.com/itsnaleeka/distributed-user-management-system/blob/main/docker-compose.yml"
click node_lint "https://github.com/itsnaleeka/distributed-user-management-system/blob/main/.golangci.yml"
click node_hooks "https://github.com/itsnaleeka/distributed-user-management-system/blob/main/.githooks/pre-commit"

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_client toneBlue
class node_gateway,node_user_service toneAmber
class node_internal_db,node_sqlc_code,node_db_models,node_sql_queries,node_migrations,node_database toneMint
class node_compose,node_lint,node_hooks toneRose
```

## Components

### External

Outside callers and entry traffic

- **Client**: caller · External user or API consumer

### Services

Deployable Go binaries

- [Gateway](https://github.com/itsnaleeka/distributed-user-management-system/blob/main/cmd/gateway/main.go): edge service · Front door that receives requests and routes user traffic · `cmd/gateway/main.go`
- [User Service](https://github.com/itsnaleeka/distributed-user-management-system/blob/main/cmd/user-service/main.go): domain service · Owns user behavior and persistence-facing application logic · `cmd/user-service/main.go`

### Data

Persistence and SQL assets

- [DB Package](https://github.com/itsnaleeka/distributed-user-management-system/blob/main/internal/db/db.go): internal data layer · Shared internal package for database access plumbing · `internal/db/db.go`
- [Generated SQL](https://github.com/itsnaleeka/distributed-user-management-system/blob/main/internal/db/users.sql.go): sqlc output · Typed Go database code generated from SQL definitions · `internal/db/users.sql.go`
- [Models](https://github.com/itsnaleeka/distributed-user-management-system/blob/main/internal/db/models.go): data models · Typed record representations used by the database layer · `internal/db/models.go`
- [Queries](https://github.com/itsnaleeka/distributed-user-management-system/blob/main/db/queries/users.sql): sql definitions · Handwritten SQL statements used as sqlc input · `db/queries/users.sql`
- [Migrations](https://github.com/itsnaleeka/distributed-user-management-system/blob/main/db/migration/0001_create_users_table.up.sql): schema migration · Versioned SQL for creating and evolving the users table · `db/migration/0001_create_users_table.up.sql`
- **Database**: relational store · External SQL database holding user data

### Workflow

Local and repository tooling

- [Compose](https://github.com/itsnaleeka/distributed-user-management-system/blob/main/docker-compose.yml): local orchestration · Container composition for local integration runs · `docker-compose.yml`
- [Linting](https://github.com/itsnaleeka/distributed-user-management-system/blob/main/.golangci.yml): static analysis · Go linting and quality checks · `.golangci.yml`
- [Git Hooks](https://github.com/itsnaleeka/distributed-user-management-system/blob/main/.githooks/pre-commit): commit checks · Repository hooks for pre-commit and commit-message checks · `.githooks/pre-commit`

## Connections

- Client → Gateway: HTTP requests · External traffic enters through the gateway
- Gateway → User Service: forward · Gateway routes user-related requests to the domain service
- User Service → DB Package: use · Service calls into the internal database access package
- DB Package → Generated SQL: implements · The DB package includes generated typed query code
- DB Package → Models: maps · Database access layer uses typed models
- Generated SQL → Queries: generated from · sqlc produces code from handwritten SQL definitions
- User Service → Database: persist · User operations ultimately read and write the SQL database
- Queries → Database: executes on · Queries are applied against the relational database
- Migrations → Database: schema changes · Migration files define and evolve the database schema
- Compose → Gateway: runs · Local composition can start the gateway service
- Compose → User Service: runs · Local composition can start the user service
- Compose → Database: provisions · Local composition can provision the database dependency
- Linting → Gateway: checks · Static analysis covers Go services and packages
- Linting → User Service: checks · Static analysis covers Go services and packages
- Git Hooks → Linting: enforces · Repository hooks reinforce code quality checks
