# shivankkapoor/standbase-backend architecture

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

- Interactive diagram: https://gitdiagram.com/shivankkapoor/standbase-backend
- Repository: https://github.com/shivankkapoor/standbase-backend

## Overview

Standbase is a REST backend for a personal standup journal. Clients authenticate through a two-step password/TOTP flow delegated to Aldrop; authenticated requests validate the device-bound session before journal and todo operations. The main domain branches are daily entries, ordered per-date todos, and yearly word-count heatmaps, with health/monitor endpoints alongside them. The graph reflects documented features and sampled controller/service/repository calls; several controller and integration details are documented but not excerpted, so those edges are omitted where call ownership cannot be verified.

Main entry points: [`src/main/java/com/shivankkapoor/standbase/service/AuthService.java`](https://github.com/shivankkapoor/standbase-backend/blob/main/src/main/java/com/shivankkapoor/standbase/service/AuthService.java) (Auth orchestration), [`src/main/java/com/shivankkapoor/standbase/controller/AuthController.java`](https://github.com/shivankkapoor/standbase-backend/blob/main/src/main/java/com/shivankkapoor/standbase/controller/AuthController.java) (Auth endpoints), [`src/main/java/com/shivankkapoor/standbase/repository/EntryRepository.java`](https://github.com/shivankkapoor/standbase-backend/blob/main/src/main/java/com/shivankkapoor/standbase/repository/EntryRepository.java) (Entry queries), [`src/main/java/com/shivankkapoor/standbase/filter/SessionAuthFilter.java`](https://github.com/shivankkapoor/standbase-backend/blob/main/src/main/java/com/shivankkapoor/standbase/filter/SessionAuthFilter.java) (Session validation filter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access and security"]
  node_auth_controller["Auth endpoints"]
  node_ip_service["Client IP<br/>[IpService.java]"]
  node_auth_service["Auth orchestration<br/>[AuthService.java]"]
  node_session_filter["Session validation filter"]
  node_user_repository["User records"]
  node_user_store[("PostgreSQL users<br/>[User.java]")]
end

subgraph group_journal["Journal and analytics"]
  node_entry_controller["Entry endpoints"]
  node_entry_service["Entry operations<br/>[EntryService.java]"]
  node_entry_repository["Entry queries"]
  node_entry_store[("PostgreSQL entries<br/>[Entry.java]")]
  node_heatmap_controller["Heatmap endpoint"]
  node_heatmap_service["Word-count analytics"]
end

subgraph group_tasks["Todo management"]
  node_todo_controller["Todo endpoints"]
  node_todo_service["Todo operations<br/>[TodoService.java]"]
  node_todo_repository["Todo queries"]
  node_todo_store[("PostgreSQL todos<br/>[Todo.java]")]
end

subgraph group_platform["Platform services"]
  node_discord["Discord alerts"]
  node_main_controller["Health and monitor"]
  node_health_service["Health checks<br/>[HealthService.java]"]
  node_health_repository["Database probe"]
end

node_client(("API client"))
node_aldrop["Aldrop auth"]
node_database[("PostgreSQL")]

node_client -->|"requests login"| node_auth_controller
node_auth_controller -->|"resolves IP"| node_ip_service
node_auth_controller -->|"delegates login"| node_auth_service
node_auth_service -->|"forwards auth"| node_aldrop
node_auth_service -->|"provisions users"| node_user_repository
node_user_repository -->|"reads and writes"| node_user_store
node_auth_service -->|"sends auth alerts"| node_discord
node_client -.->|"sends protected request"| node_session_filter
node_session_filter -->|"validates token"| node_auth_service
node_client -->|"requests entries"| node_entry_controller
node_entry_controller -->|"delegates entry work"| node_entry_service
node_entry_service -->|"queries and saves"| node_entry_repository
node_entry_repository -->|"persists entries"| node_entry_store
node_entry_store -.->|"stored in"| node_database
node_client -->|"requests heatmap"| node_heatmap_controller
node_heatmap_controller -->|"delegates analytics"| node_heatmap_service
node_heatmap_service -->|"reads word counts"| node_entry_repository
node_client -->|"requests todos"| node_todo_controller
node_todo_controller -->|"delegates todo work"| node_todo_service
node_todo_service -->|"queries and saves"| node_todo_repository
node_todo_repository -->|"persists todos"| node_todo_store
node_todo_store -.->|"stored in"| node_database
node_client -->|"requests status"| node_main_controller
node_main_controller -->|"delegates health checks"| node_health_service
node_health_service -->|"checks database"| node_health_repository
node_health_repository -.->|"probes"| node_database

click node_auth_controller "https://github.com/shivankkapoor/standbase-backend/blob/main/src/main/java/com/shivankkapoor/standbase/controller/AuthController.java"
click node_ip_service "https://github.com/shivankkapoor/standbase-backend/blob/main/src/main/java/com/shivankkapoor/standbase/service/IpService.java"
click node_auth_service "https://github.com/shivankkapoor/standbase-backend/blob/main/src/main/java/com/shivankkapoor/standbase/service/AuthService.java"
click node_session_filter "https://github.com/shivankkapoor/standbase-backend/blob/main/src/main/java/com/shivankkapoor/standbase/filter/SessionAuthFilter.java"
click node_discord "https://github.com/shivankkapoor/standbase-backend/blob/main/src/main/java/com/shivankkapoor/standbase/service/DiscordService.java"
click node_entry_controller "https://github.com/shivankkapoor/standbase-backend/blob/main/src/main/java/com/shivankkapoor/standbase/controller/EntryController.java"
click node_entry_service "https://github.com/shivankkapoor/standbase-backend/blob/main/src/main/java/com/shivankkapoor/standbase/service/EntryService.java"
click node_entry_repository "https://github.com/shivankkapoor/standbase-backend/blob/main/src/main/java/com/shivankkapoor/standbase/repository/EntryRepository.java"
click node_entry_store "https://github.com/shivankkapoor/standbase-backend/blob/main/src/main/java/com/shivankkapoor/standbase/model/Entry.java"
click node_heatmap_controller "https://github.com/shivankkapoor/standbase-backend/blob/main/src/main/java/com/shivankkapoor/standbase/controller/HeatMapController.java"
click node_heatmap_service "https://github.com/shivankkapoor/standbase-backend/blob/main/src/main/java/com/shivankkapoor/standbase/service/HeatMapService.java"
click node_todo_controller "https://github.com/shivankkapoor/standbase-backend/blob/main/src/main/java/com/shivankkapoor/standbase/controller/TodoController.java"
click node_todo_service "https://github.com/shivankkapoor/standbase-backend/blob/main/src/main/java/com/shivankkapoor/standbase/service/TodoService.java"
click node_todo_repository "https://github.com/shivankkapoor/standbase-backend/blob/main/src/main/java/com/shivankkapoor/standbase/repository/TodoRepository.java"
click node_todo_store "https://github.com/shivankkapoor/standbase-backend/blob/main/src/main/java/com/shivankkapoor/standbase/model/Todo.java"
click node_user_repository "https://github.com/shivankkapoor/standbase-backend/blob/main/src/main/java/com/shivankkapoor/standbase/repository/UserRepository.java"
click node_user_store "https://github.com/shivankkapoor/standbase-backend/blob/main/src/main/java/com/shivankkapoor/standbase/model/User.java"
click node_main_controller "https://github.com/shivankkapoor/standbase-backend/blob/main/src/main/java/com/shivankkapoor/standbase/controller/MainController.java"
click node_health_service "https://github.com/shivankkapoor/standbase-backend/blob/main/src/main/java/com/shivankkapoor/standbase/service/HealthService.java"
click node_health_repository "https://github.com/shivankkapoor/standbase-backend/blob/main/src/main/java/com/shivankkapoor/standbase/repository/HealthRepository.java"

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_auth_controller,node_ip_service,node_auth_service,node_session_filter,node_user_repository,node_user_store,node_client toneBlue
class node_entry_controller,node_entry_service,node_entry_repository,node_entry_store,node_heatmap_controller,node_heatmap_service,node_database toneAmber
class node_todo_controller,node_todo_service,node_todo_repository,node_todo_store toneMint
class node_discord,node_main_controller,node_health_service,node_health_repository toneRose
class node_aldrop toneIndigo
```

## Components

### Access and security

- [Auth endpoints](https://github.com/shivankkapoor/standbase-backend/blob/main/src/main/java/com/shivankkapoor/standbase/controller/AuthController.java): `src/main/java/com/shivankkapoor/standbase/controller/AuthController.java`
- [Client IP](https://github.com/shivankkapoor/standbase-backend/blob/main/src/main/java/com/shivankkapoor/standbase/service/IpService.java): `src/main/java/com/shivankkapoor/standbase/service/IpService.java`
- [Auth orchestration](https://github.com/shivankkapoor/standbase-backend/blob/main/src/main/java/com/shivankkapoor/standbase/service/AuthService.java): `src/main/java/com/shivankkapoor/standbase/service/AuthService.java`
- [Session validation filter](https://github.com/shivankkapoor/standbase-backend/blob/main/src/main/java/com/shivankkapoor/standbase/filter/SessionAuthFilter.java): `src/main/java/com/shivankkapoor/standbase/filter/SessionAuthFilter.java`
- [User records](https://github.com/shivankkapoor/standbase-backend/blob/main/src/main/java/com/shivankkapoor/standbase/repository/UserRepository.java): `src/main/java/com/shivankkapoor/standbase/repository/UserRepository.java`
- [PostgreSQL users](https://github.com/shivankkapoor/standbase-backend/blob/main/src/main/java/com/shivankkapoor/standbase/model/User.java): `src/main/java/com/shivankkapoor/standbase/model/User.java`

### Journal and analytics

- [Entry endpoints](https://github.com/shivankkapoor/standbase-backend/blob/main/src/main/java/com/shivankkapoor/standbase/controller/EntryController.java): `src/main/java/com/shivankkapoor/standbase/controller/EntryController.java`
- [Entry operations](https://github.com/shivankkapoor/standbase-backend/blob/main/src/main/java/com/shivankkapoor/standbase/service/EntryService.java): `src/main/java/com/shivankkapoor/standbase/service/EntryService.java`
- [Entry queries](https://github.com/shivankkapoor/standbase-backend/blob/main/src/main/java/com/shivankkapoor/standbase/repository/EntryRepository.java): `src/main/java/com/shivankkapoor/standbase/repository/EntryRepository.java`
- [PostgreSQL entries](https://github.com/shivankkapoor/standbase-backend/blob/main/src/main/java/com/shivankkapoor/standbase/model/Entry.java): `src/main/java/com/shivankkapoor/standbase/model/Entry.java`
- [Heatmap endpoint](https://github.com/shivankkapoor/standbase-backend/blob/main/src/main/java/com/shivankkapoor/standbase/controller/HeatMapController.java): `src/main/java/com/shivankkapoor/standbase/controller/HeatMapController.java`
- [Word-count analytics](https://github.com/shivankkapoor/standbase-backend/blob/main/src/main/java/com/shivankkapoor/standbase/service/HeatMapService.java): `src/main/java/com/shivankkapoor/standbase/service/HeatMapService.java`

### Todo management

- [Todo endpoints](https://github.com/shivankkapoor/standbase-backend/blob/main/src/main/java/com/shivankkapoor/standbase/controller/TodoController.java): `src/main/java/com/shivankkapoor/standbase/controller/TodoController.java`
- [Todo operations](https://github.com/shivankkapoor/standbase-backend/blob/main/src/main/java/com/shivankkapoor/standbase/service/TodoService.java): `src/main/java/com/shivankkapoor/standbase/service/TodoService.java`
- [Todo queries](https://github.com/shivankkapoor/standbase-backend/blob/main/src/main/java/com/shivankkapoor/standbase/repository/TodoRepository.java): `src/main/java/com/shivankkapoor/standbase/repository/TodoRepository.java`
- [PostgreSQL todos](https://github.com/shivankkapoor/standbase-backend/blob/main/src/main/java/com/shivankkapoor/standbase/model/Todo.java): `src/main/java/com/shivankkapoor/standbase/model/Todo.java`

### Platform services

- [Discord alerts](https://github.com/shivankkapoor/standbase-backend/blob/main/src/main/java/com/shivankkapoor/standbase/service/DiscordService.java): `src/main/java/com/shivankkapoor/standbase/service/DiscordService.java`
- [Health and monitor](https://github.com/shivankkapoor/standbase-backend/blob/main/src/main/java/com/shivankkapoor/standbase/controller/MainController.java): `src/main/java/com/shivankkapoor/standbase/controller/MainController.java`
- [Health checks](https://github.com/shivankkapoor/standbase-backend/blob/main/src/main/java/com/shivankkapoor/standbase/service/HealthService.java): `src/main/java/com/shivankkapoor/standbase/service/HealthService.java`
- [Database probe](https://github.com/shivankkapoor/standbase-backend/blob/main/src/main/java/com/shivankkapoor/standbase/repository/HealthRepository.java): `src/main/java/com/shivankkapoor/standbase/repository/HealthRepository.java`

### Other components

- **API client**
- **Aldrop auth**
- **PostgreSQL**

## Connections

- API client → Auth endpoints: requests login (evidence: `src/main/java/com/shivankkapoor/standbase/controller/AuthController.java`)
- Auth endpoints → Client IP: resolves IP (evidence: `src/main/java/com/shivankkapoor/standbase/controller/AuthController.java`)
- Auth endpoints → Auth orchestration: delegates login (evidence: `src/main/java/com/shivankkapoor/standbase/controller/AuthController.java`)
- Auth orchestration → Aldrop auth: forwards auth (evidence: `src/main/java/com/shivankkapoor/standbase/service/AuthService.java`)
- Auth orchestration → User records: provisions users (evidence: `src/main/java/com/shivankkapoor/standbase/service/AuthService.java`)
- User records → PostgreSQL users: reads and writes (evidence: `src/main/java/com/shivankkapoor/standbase/repository/UserRepository.java`)
- Auth orchestration → Discord alerts: sends auth alerts (evidence: `src/main/java/com/shivankkapoor/standbase/service/AuthService.java`)
- API client → Session validation filter: sends protected request (evidence: `README.md`)
- Session validation filter → Auth orchestration: validates token (evidence: `src/main/java/com/shivankkapoor/standbase/filter/SessionAuthFilter.java`)
- API client → Entry endpoints: requests entries (evidence: `src/main/java/com/shivankkapoor/standbase/controller/EntryController.java`)
- Entry endpoints → Entry operations: delegates entry work (evidence: `src/main/java/com/shivankkapoor/standbase/controller/EntryController.java`)
- Entry operations → Entry queries: queries and saves (evidence: `src/main/java/com/shivankkapoor/standbase/service/EntryService.java`)
- Entry queries → PostgreSQL entries: persists entries (evidence: `src/main/java/com/shivankkapoor/standbase/repository/EntryRepository.java`)
- PostgreSQL entries → PostgreSQL: stored in (evidence: `README.md`)
- API client → Heatmap endpoint: requests heatmap (evidence: `src/main/java/com/shivankkapoor/standbase/controller/HeatMapController.java`)
- Heatmap endpoint → Word-count analytics: delegates analytics (evidence: `src/main/java/com/shivankkapoor/standbase/controller/HeatMapController.java`)
- Word-count analytics → Entry queries: reads word counts (evidence: `src/main/java/com/shivankkapoor/standbase/service/HeatMapService.java`)
- API client → Todo endpoints: requests todos (evidence: `src/main/java/com/shivankkapoor/standbase/controller/TodoController.java`)
- Todo endpoints → Todo operations: delegates todo work (evidence: `src/main/java/com/shivankkapoor/standbase/controller/TodoController.java`)
- Todo operations → Todo queries: queries and saves (evidence: `src/main/java/com/shivankkapoor/standbase/service/TodoService.java`)
- Todo queries → PostgreSQL todos: persists todos (evidence: `src/main/java/com/shivankkapoor/standbase/repository/TodoRepository.java`)
- PostgreSQL todos → PostgreSQL: stored in (evidence: `README.md`)
- API client → Health and monitor: requests status (evidence: `src/main/java/com/shivankkapoor/standbase/controller/MainController.java`)
- Health and monitor → Health checks: delegates health checks (evidence: `src/main/java/com/shivankkapoor/standbase/controller/MainController.java`)
- Health checks → Database probe: checks database (evidence: `src/main/java/com/shivankkapoor/standbase/service/HealthService.java`)
- Database probe → PostgreSQL: probes (evidence: `README.md`)