# shubhamranswal/ciphergate architecture

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

- Interactive diagram: https://gitdiagram.com/shubhamranswal/ciphergate
- Repository: https://github.com/shubhamranswal/ciphergate

## Overview

CipherGate is an interactive CLI authentication system. Users register, log in with password and optionally TOTP, receive a managed session, and can inspect their account, manage MFA, or log out. Services enforce user and session rules over PostgreSQL-backed repositories; startup wires those components and runs migrations. The graph follows the supplied excerpts and README; unshown implementation details are represented only where documented, and uncertain links are omitted.

Main entry points: [`internal/cli/shell.go`](https://github.com/shubhamranswal/ciphergate/blob/master/internal/cli/shell.go) (Command Shell), [`internal/user/service.go`](https://github.com/shubhamranswal/ciphergate/blob/master/internal/user/service.go) (User Service), [`main.go`](https://github.com/shubhamranswal/ciphergate/blob/master/main.go) (Application Startup), [`internal/session/service.go`](https://github.com/shubhamranswal/ciphergate/blob/master/internal/session/service.go) (Session Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["Interactive CLI"]
  node_shell["Command Shell<br/>[shell.go]"]
  node_registration["Registration<br/>[register.go]"]
  node_login["Login Flow<br/>[login.go]"]
  node_mfa_cli["MFA Commands<br/>[enable_2fa.go]"]
  node_logout["Logout<br/>[logout.go]"]
  node_session_guard["Session Guard<br/>[session_guard.go]"]
  node_whoami["Account Details<br/>[whoami.go]"]
end

subgraph group_services["Identity Services"]
  node_auth_context["Auth Context<br/>[context.go]"]
  node_user_service["User Service<br/>[service.go]"]
  node_session_service["Session Service<br/>[service.go]"]
  node_mfa_service["TOTP Service<br/>[service.go]"]
end

subgraph group_persistence["Persistence"]
  node_user_repository["User Repository"]
  node_session_repository["Session Repository"]
  node_database["PostgreSQL Connection<br/>[postgres.go]"]
  node_postgres[("PostgreSQL")]
  node_migration_runner["Migration Runner<br/>[runner.go]"]
  node_schema["Database Schema"]
end

subgraph group_runtime["Runtime Setup"]
  node_main["Application Startup<br/>[main.go]"]
  node_configuration["Runtime Configuration<br/>[config.go]"]
end

node_operator(("CLI User"))

node_operator -->|"enters commands"| node_shell
node_shell -->|"dispatches register"| node_registration
node_shell -->|"dispatches login"| node_login
node_shell -->|"dispatches MFA"| node_mfa_cli
node_shell -->|"dispatches logout"| node_logout
node_shell -->|"validates session"| node_session_guard
node_shell -->|"dispatches details"| node_whoami
node_registration -->|"registers user"| node_user_service
node_login -->|"authenticates password"| node_user_service
node_login -->|"verifies TOTP"| node_mfa_service
node_login -->|"creates MFA session"| node_session_service
node_login -->|"updates login times"| node_user_service
node_login -->|"sets authenticated state"| node_auth_context
node_mfa_cli -->|"generates and verifies"| node_mfa_service
node_mfa_cli -->|"updates MFA settings"| node_user_service
node_logout -->|"deactivates session"| node_session_service
node_logout -->|"clears auth state"| node_auth_context
node_session_guard -->|"checks and clears state"| node_auth_context
node_session_guard -->|"validates and deactivates"| node_session_service
node_whoami -->|"reads user details"| node_auth_context
node_user_service -->|"reads and updates users"| node_user_repository
node_user_service -->|"creates login session"| node_session_service
node_session_service -->|"creates and validates"| node_session_repository
node_user_service -->|"reads lockout settings"| node_configuration
node_session_service -->|"reads session timeout"| node_configuration
node_user_repository -.->|"uses database connection"| node_database
node_session_repository -.->|"uses database connection"| node_database
node_database -->|"connects to"| node_postgres
node_main -->|"loads settings"| node_configuration
node_main -->|"connects"| node_database
node_main -->|"runs migrations"| node_migration_runner
node_main -->|"wires user service"| node_user_service
node_main -->|"wires session service"| node_session_service
node_main -->|"wires MFA service"| node_mfa_service
node_main -->|"starts CLI"| node_shell
node_migration_runner -.->|"applies schema"| node_schema
node_user_repository -->|"persists user data"| node_postgres
node_session_repository -->|"persists sessions"| node_postgres

click node_shell "https://github.com/shubhamranswal/ciphergate/blob/master/internal/cli/shell.go"
click node_registration "https://github.com/shubhamranswal/ciphergate/blob/master/internal/cli/register.go"
click node_login "https://github.com/shubhamranswal/ciphergate/blob/master/internal/cli/login.go"
click node_mfa_cli "https://github.com/shubhamranswal/ciphergate/blob/master/internal/cli/enable_2fa.go"
click node_logout "https://github.com/shubhamranswal/ciphergate/blob/master/internal/cli/logout.go"
click node_session_guard "https://github.com/shubhamranswal/ciphergate/blob/master/internal/cli/session_guard.go"
click node_whoami "https://github.com/shubhamranswal/ciphergate/blob/master/internal/cli/whoami.go"
click node_auth_context "https://github.com/shubhamranswal/ciphergate/blob/master/internal/auth/context.go"
click node_user_service "https://github.com/shubhamranswal/ciphergate/blob/master/internal/user/service.go"
click node_session_service "https://github.com/shubhamranswal/ciphergate/blob/master/internal/session/service.go"
click node_mfa_service "https://github.com/shubhamranswal/ciphergate/blob/master/internal/mfa/service.go"
click node_user_repository "https://github.com/shubhamranswal/ciphergate/blob/master/internal/user/postgres_repository.go"
click node_session_repository "https://github.com/shubhamranswal/ciphergate/blob/master/internal/session/postgres_repository.go"
click node_database "https://github.com/shubhamranswal/ciphergate/blob/master/internal/database/postgres.go"
click node_migration_runner "https://github.com/shubhamranswal/ciphergate/blob/master/internal/migration/runner.go"
click node_schema "https://github.com/shubhamranswal/ciphergate/blob/master/migrations/001_create_users.sql"
click node_main "https://github.com/shubhamranswal/ciphergate/blob/master/main.go"
click node_configuration "https://github.com/shubhamranswal/ciphergate/blob/master/internal/config/config.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_shell,node_registration,node_login,node_mfa_cli,node_logout,node_session_guard,node_whoami,node_operator toneBlue
class node_auth_context,node_user_service,node_session_service,node_mfa_service toneAmber
class node_user_repository,node_session_repository,node_database,node_postgres,node_migration_runner,node_schema toneMint
class node_main,node_configuration toneRose
```

## Components

### Interactive CLI

- [Command Shell](https://github.com/shubhamranswal/ciphergate/blob/master/internal/cli/shell.go): `internal/cli/shell.go`
- [Registration](https://github.com/shubhamranswal/ciphergate/blob/master/internal/cli/register.go): `internal/cli/register.go`
- [Login Flow](https://github.com/shubhamranswal/ciphergate/blob/master/internal/cli/login.go): `internal/cli/login.go`
- [MFA Commands](https://github.com/shubhamranswal/ciphergate/blob/master/internal/cli/enable_2fa.go): `internal/cli/enable_2fa.go`
- [Logout](https://github.com/shubhamranswal/ciphergate/blob/master/internal/cli/logout.go): `internal/cli/logout.go`
- [Session Guard](https://github.com/shubhamranswal/ciphergate/blob/master/internal/cli/session_guard.go): `internal/cli/session_guard.go`
- [Account Details](https://github.com/shubhamranswal/ciphergate/blob/master/internal/cli/whoami.go): `internal/cli/whoami.go`

### Identity Services

- [Auth Context](https://github.com/shubhamranswal/ciphergate/blob/master/internal/auth/context.go): `internal/auth/context.go`
- [User Service](https://github.com/shubhamranswal/ciphergate/blob/master/internal/user/service.go): `internal/user/service.go`
- [Session Service](https://github.com/shubhamranswal/ciphergate/blob/master/internal/session/service.go): `internal/session/service.go`
- [TOTP Service](https://github.com/shubhamranswal/ciphergate/blob/master/internal/mfa/service.go): `internal/mfa/service.go`

### Persistence

- [User Repository](https://github.com/shubhamranswal/ciphergate/blob/master/internal/user/postgres_repository.go): `internal/user/postgres_repository.go`
- [Session Repository](https://github.com/shubhamranswal/ciphergate/blob/master/internal/session/postgres_repository.go): `internal/session/postgres_repository.go`
- [PostgreSQL Connection](https://github.com/shubhamranswal/ciphergate/blob/master/internal/database/postgres.go): `internal/database/postgres.go`
- **PostgreSQL**
- [Migration Runner](https://github.com/shubhamranswal/ciphergate/blob/master/internal/migration/runner.go): `internal/migration/runner.go`
- [Database Schema](https://github.com/shubhamranswal/ciphergate/blob/master/migrations/001_create_users.sql): `migrations/001_create_users.sql`

### Runtime Setup

- [Application Startup](https://github.com/shubhamranswal/ciphergate/blob/master/main.go): `main.go`
- [Runtime Configuration](https://github.com/shubhamranswal/ciphergate/blob/master/internal/config/config.go): `internal/config/config.go`

### Other components

- **CLI User**

## Connections

- CLI User → Command Shell: enters commands (evidence: `README.md`)
- Command Shell → Registration: dispatches register (evidence: `internal/cli/shell.go`)
- Command Shell → Login Flow: dispatches login (evidence: `internal/cli/shell.go`)
- Command Shell → MFA Commands: dispatches MFA (evidence: `internal/cli/shell.go`)
- Command Shell → Logout: dispatches logout (evidence: `internal/cli/shell.go`)
- Command Shell → Session Guard: validates session (evidence: `internal/cli/shell.go`)
- Command Shell → Account Details: dispatches details (evidence: `internal/cli/shell.go`)
- Registration → User Service: registers user (evidence: `internal/cli/register.go`)
- Login Flow → User Service: authenticates password (evidence: `internal/cli/login.go`)
- Login Flow → TOTP Service: verifies TOTP (evidence: `internal/cli/login.go`)
- Login Flow → Session Service: creates MFA session (evidence: `internal/cli/login.go`)
- Login Flow → User Service: updates login times (evidence: `internal/cli/login.go`)
- Login Flow → Auth Context: sets authenticated state (evidence: `internal/cli/login.go`)
- MFA Commands → TOTP Service: generates and verifies (evidence: `internal/cli/enable_2fa.go`)
- MFA Commands → User Service: updates MFA settings (evidence: `internal/cli/enable_2fa.go`)
- Logout → Session Service: deactivates session (evidence: `internal/cli/logout.go`)
- Logout → Auth Context: clears auth state (evidence: `internal/cli/logout.go`)
- Session Guard → Auth Context: checks and clears state (evidence: `internal/cli/session_guard.go`)
- Session Guard → Session Service: validates and deactivates (evidence: `internal/cli/session_guard.go`)
- Account Details → Auth Context: reads user details (evidence: `internal/cli/whoami.go`)
- User Service → User Repository: reads and updates users (evidence: `internal/user/service.go`)
- User Service → Session Service: creates login session (evidence: `internal/user/service.go`)
- Session Service → Session Repository: creates and validates (evidence: `internal/session/service.go`)
- User Service → Runtime Configuration: reads lockout settings (evidence: `internal/user/service.go`)
- Session Service → Runtime Configuration: reads session timeout (evidence: `internal/session/service.go`)
- User Repository → PostgreSQL Connection: uses database connection
- Session Repository → PostgreSQL Connection: uses database connection
- PostgreSQL Connection → PostgreSQL: connects to (evidence: `README.md`)
- Application Startup → Runtime Configuration: loads settings (evidence: `main.go`)
- Application Startup → PostgreSQL Connection: connects (evidence: `main.go`)
- Application Startup → Migration Runner: runs migrations (evidence: `main.go`)
- Application Startup → User Service: wires user service (evidence: `main.go`)
- Application Startup → Session Service: wires session service (evidence: `main.go`)
- Application Startup → TOTP Service: wires MFA service (evidence: `main.go`)
- Application Startup → Command Shell: starts CLI (evidence: `main.go`)
- Migration Runner → Database Schema: applies schema
- User Repository → PostgreSQL: persists user data (evidence: `README.md`)
- Session Repository → PostgreSQL: persists sessions (evidence: `README.md`)
