# sebasvelasco353/nummus architecture

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

- Interactive diagram: https://gitdiagram.com/sebasvelasco353/nummus
- Repository: https://github.com/sebasvelasco353/nummus

## Overview

Nummus is a self-hosted home-finance tracker with a Go/Gin API and PostgreSQL. The visible user workflow covers signup and login, token-based access, and authenticated account management; refresh and logout manage sessions. The README also names categories and transactions as part of the finance domain, though this tree shows their migrations rather than API handlers. The sampled source supports the API, auth, and account relationships; unsampled capabilities and database schema links are shown only where documentation or the tree supports them.

Main entry points: [`server/cmd/main.go`](https://github.com/sebasvelasco353/nummus/blob/dev/server/cmd/main.go) (API startup), [`server/internal/users/users.model.go`](https://github.com/sebasvelasco353/nummus/blob/dev/server/internal/users/users.model.go) (User operations), [`server/internal/users/users.controller.go`](https://github.com/sebasvelasco353/nummus/blob/dev/server/internal/users/users.controller.go) (User handlers), [`server/internal/config/config.go`](https://github.com/sebasvelasco353/nummus/blob/dev/server/internal/config/config.go) (Server config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API runtime"]
  node_main["API startup<br/>[main.go]"]
  node_user_routes["User routes<br/>[users.routes.go]"]
  node_account_routes["Account routes<br/>[accounts.routes.go]"]
end

subgraph group_identity["Identity and sessions"]
  node_user_controller["User handlers"]
  node_user_model["User operations<br/>[users.model.go]"]
  node_middleware["JWT middleware<br/>[auth.go]"]
  node_access_tokens["Access tokens<br/>[accessToken.go]"]
  node_refresh_tokens["Refresh tokens<br/>[refreshToken.go]"]
  node_passwords["Password hashing<br/>[password.go]"]
  node_hash["Token hashing<br/>[hash.go]"]
end

subgraph group_finance["Finance domain"]
  node_account_controller["Account handlers"]
  node_account_model["Account operations<br/>[accounts.model.go]"]
  node_finance_schema["Finance schema"]
end

subgraph group_persistence["Persistence"]
  node_config["Server config<br/>[config.go]"]
  node_db_config["Database connection<br/>[database.go]"]
  node_postgres[("PostgreSQL")]
end

node_client(("Web client"))

node_client -->|"sends requests"| node_main
node_main -->|"loads settings"| node_config
node_main -->|"connects database"| node_db_config
node_main -->|"registers routes"| node_user_routes
node_main -->|"registers routes"| node_account_routes
node_user_routes -->|"routes requests"| node_user_controller
node_account_routes -->|"routes requests"| node_account_controller
node_user_routes -->|"protects profile"| node_middleware
node_account_routes -->|"protects accounts"| node_middleware
node_user_controller -->|"runs signup/login"| node_user_model
node_user_controller -->|"rotates sessions"| node_refresh_tokens
node_user_controller -->|"hashes cookie token"| node_hash
node_user_model -->|"hashes credentials"| node_passwords
node_user_model -->|"issues access token"| node_access_tokens
node_user_model -->|"persists refresh token"| node_refresh_tokens
node_middleware -->|"validates token"| node_access_tokens
node_account_controller -->|"runs account operations"| node_account_model
node_account_model -->|"queries database"| node_config
node_user_model -->|"queries database"| node_config
node_refresh_tokens -->|"queries database"| node_config
node_db_config -->|"opens connection"| node_postgres
node_finance_schema -.->|"defines finance tables"| node_postgres

click node_main "https://github.com/sebasvelasco353/nummus/blob/dev/server/cmd/main.go"
click node_user_routes "https://github.com/sebasvelasco353/nummus/blob/dev/server/internal/users/users.routes.go"
click node_account_routes "https://github.com/sebasvelasco353/nummus/blob/dev/server/internal/accounts/accounts.routes.go"
click node_user_controller "https://github.com/sebasvelasco353/nummus/blob/dev/server/internal/users/users.controller.go"
click node_user_model "https://github.com/sebasvelasco353/nummus/blob/dev/server/internal/users/users.model.go"
click node_middleware "https://github.com/sebasvelasco353/nummus/blob/dev/server/internal/middleware/auth.go"
click node_access_tokens "https://github.com/sebasvelasco353/nummus/blob/dev/server/internal/auth/accessToken.go"
click node_refresh_tokens "https://github.com/sebasvelasco353/nummus/blob/dev/server/internal/auth/refreshToken.go"
click node_passwords "https://github.com/sebasvelasco353/nummus/blob/dev/server/internal/auth/password.go"
click node_hash "https://github.com/sebasvelasco353/nummus/blob/dev/server/internal/utils/hash.go"
click node_account_controller "https://github.com/sebasvelasco353/nummus/blob/dev/server/internal/accounts/accounts.controller.go"
click node_account_model "https://github.com/sebasvelasco353/nummus/blob/dev/server/internal/accounts/accounts.model.go"
click node_finance_schema "https://github.com/sebasvelasco353/nummus/tree/dev/server/internal/database/migrations"
click node_config "https://github.com/sebasvelasco353/nummus/blob/dev/server/internal/config/config.go"
click node_db_config "https://github.com/sebasvelasco353/nummus/blob/dev/server/internal/config/database.go"

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_main,node_user_routes,node_account_routes,node_client toneBlue
class node_user_controller,node_user_model,node_middleware,node_access_tokens,node_refresh_tokens,node_passwords,node_hash toneAmber
class node_account_controller,node_account_model,node_finance_schema toneMint
class node_config,node_db_config,node_postgres toneRose
```

## Components

### API runtime

- [API startup](https://github.com/sebasvelasco353/nummus/blob/dev/server/cmd/main.go): `server/cmd/main.go`
- [User routes](https://github.com/sebasvelasco353/nummus/blob/dev/server/internal/users/users.routes.go): `server/internal/users/users.routes.go`
- [Account routes](https://github.com/sebasvelasco353/nummus/blob/dev/server/internal/accounts/accounts.routes.go): `server/internal/accounts/accounts.routes.go`

### Identity and sessions

- [User handlers](https://github.com/sebasvelasco353/nummus/blob/dev/server/internal/users/users.controller.go): `server/internal/users/users.controller.go`
- [User operations](https://github.com/sebasvelasco353/nummus/blob/dev/server/internal/users/users.model.go): `server/internal/users/users.model.go`
- [JWT middleware](https://github.com/sebasvelasco353/nummus/blob/dev/server/internal/middleware/auth.go): `server/internal/middleware/auth.go`
- [Access tokens](https://github.com/sebasvelasco353/nummus/blob/dev/server/internal/auth/accessToken.go): `server/internal/auth/accessToken.go`
- [Refresh tokens](https://github.com/sebasvelasco353/nummus/blob/dev/server/internal/auth/refreshToken.go): `server/internal/auth/refreshToken.go`
- [Password hashing](https://github.com/sebasvelasco353/nummus/blob/dev/server/internal/auth/password.go): `server/internal/auth/password.go`
- [Token hashing](https://github.com/sebasvelasco353/nummus/blob/dev/server/internal/utils/hash.go): `server/internal/utils/hash.go`

### Finance domain

- [Account handlers](https://github.com/sebasvelasco353/nummus/blob/dev/server/internal/accounts/accounts.controller.go): `server/internal/accounts/accounts.controller.go`
- [Account operations](https://github.com/sebasvelasco353/nummus/blob/dev/server/internal/accounts/accounts.model.go): `server/internal/accounts/accounts.model.go`
- [Finance schema](https://github.com/sebasvelasco353/nummus/tree/dev/server/internal/database/migrations): `server/internal/database/migrations`

### Persistence

- [Server config](https://github.com/sebasvelasco353/nummus/blob/dev/server/internal/config/config.go): `server/internal/config/config.go`
- [Database connection](https://github.com/sebasvelasco353/nummus/blob/dev/server/internal/config/database.go): `server/internal/config/database.go`
- **PostgreSQL**

### Other components

- **Web client**

## Connections

- Web client → API startup: sends requests (evidence: `README.md`)
- API startup → Server config: loads settings (evidence: `server/cmd/main.go`)
- API startup → Database connection: connects database (evidence: `server/cmd/main.go`)
- API startup → User routes: registers routes (evidence: `server/cmd/main.go`)
- API startup → Account routes: registers routes (evidence: `server/cmd/main.go`)
- User routes → User handlers: routes requests (evidence: `server/internal/users/users.routes.go`)
- Account routes → Account handlers: routes requests (evidence: `server/internal/accounts/accounts.routes.go`)
- User routes → JWT middleware: protects profile (evidence: `server/internal/users/users.routes.go`)
- Account routes → JWT middleware: protects accounts (evidence: `server/internal/accounts/accounts.routes.go`)
- User handlers → User operations: runs signup/login (evidence: `server/internal/users/users.controller.go`)
- User handlers → Refresh tokens: rotates sessions (evidence: `server/internal/users/users.controller.go`)
- User handlers → Token hashing: hashes cookie token (evidence: `server/internal/users/users.controller.go`)
- User operations → Password hashing: hashes credentials (evidence: `server/internal/users/users.model.go`)
- User operations → Access tokens: issues access token (evidence: `server/internal/users/users.model.go`)
- User operations → Refresh tokens: persists refresh token (evidence: `server/internal/users/users.model.go`)
- JWT middleware → Access tokens: validates token (evidence: `server/internal/middleware/auth.go`)
- Account handlers → Account operations: runs account operations (evidence: `server/internal/accounts/accounts.controller.go`)
- Account operations → Server config: queries database (evidence: `server/internal/accounts/accounts.model.go`)
- User operations → Server config: queries database (evidence: `server/internal/users/users.model.go`)
- Refresh tokens → Server config: queries database (evidence: `server/internal/auth/refreshToken.go`)
- Database connection → PostgreSQL: opens connection (evidence: `server/internal/config/database.go`)
- Finance schema → PostgreSQL: defines finance tables (evidence: `README.md`)
