How itsnaleeka/distributed-user-management-system works
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: user-service/main.go User Service · gateway/main.go Gateway · docker-compose.yml Compose · db.go DB Package
Components 12
External
Outside callers and entry traffic
- Client · External user or API consumer
Services
Deployable Go binaries
- Gateway · Front door that receives requests and routes user traffic
cmd/gateway/main.go - User Service · Owns user behavior and persistence-facing application logic
cmd/user-service/main.go
Data
Persistence and SQL assets
- DB Package · Shared internal package for database access plumbing
internal/db/db.go - Generated SQL · Typed Go database code generated from SQL definitions
internal/db/users.sql.go - Models · Typed record representations used by the database layer
internal/db/models.go - Queries · Handwritten SQL statements used as sqlc input
db/queries/users.sql - Migrations · Versioned SQL for creating and evolving the users table
db/migration/0001_create_users_table.up.sql - Database · External SQL database holding user data
Connections 15
- 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