# iyed523/securevault architecture

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

- Interactive diagram: https://gitdiagram.com/iyed523/securevault
- Repository: https://github.com/iyed523/securevault

## Overview

SecureVault is a personal secrets-vault REST API. Its documented user workflow is registration or login, authenticated secret management with owner-only access, and revocable sessions maintained through refresh-token rotation; secret contents are encrypted while titles remain searchable in clear text. The graph includes authentication, rate limiting, persistence, readiness, and request observability. The supplied tree and excerpts do not include the documented secret CRUD/encryption implementation, so that capability is represented at the application level without inventing source modules or internal call paths.

Main entry points: [`app/api/routes/auth.py`](https://github.com/iyed523/securevault/blob/main/app/api/routes/auth.py) (Auth endpoints), [`app/services/login.py`](https://github.com/iyed523/securevault/blob/main/app/services/login.py) (Login flow), [`app/services/refresh.py`](https://github.com/iyed523/securevault/blob/main/app/services/refresh.py) (Refresh and replay control), [`app/repositories/users.py`](https://github.com/iyed523/securevault/blob/main/app/repositories/users.py) (User repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_http["HTTP API"]
  node_application["FastAPI application<br/>[main.py]"]
  node_router["API router<br/>[router.py]"]
  node_auth_routes["Auth endpoints<br/>[auth.py]"]
  node_health["Health endpoint<br/>[health.py]"]
  node_readiness["Readiness endpoint<br/>[ready.py]"]
  node_schemas["Auth and user contracts<br/>[auth.py]"]
end

subgraph group_auth["Identity and security"]
  node_auth_services["Registration and login<br/>[registration.py]"]
  node_login_service["Login flow<br/>[login.py]"]
  node_refresh_service["Refresh and replay control<br/>[refresh.py]"]
  node_logout_service["Session logout<br/>[logout.py]"]
  node_auth_dependency["Request authentication<br/>[dependencies.py]"]
  node_token_security["JWT access tokens<br/>[tokens.py]"]
  node_refresh_security["Refresh-token primitives<br/>[refresh_tokens.py]"]
  node_rate_limiting["Rate limiting<br/>[rate_limit.py]"]
end

subgraph group_persistence["Persistence"]
  node_users_repo["User repository<br/>[users.py]"]
  node_sessions_repo["Session repository<br/>[sessions.py]"]
  node_refresh_repo["Refresh-token repository<br/>[refresh_tokens.py]"]
  node_models["User and session models<br/>[session.py]"]
  node_db_session["Database sessions<br/>[session.py]"]
  node_postgres[("PostgreSQL")]
end

subgraph group_runtime["Runtime infrastructure"]
  node_redis["Redis pool<br/>[redis.py]"]
  node_readiness_check["Dependency readiness<br/>[readiness.py]"]
  node_middleware["Request middleware<br/>[middleware.py]"]
  node_request_logging["Structured logging<br/>[logging.py]"]
  node_configuration["Runtime configuration<br/>[config.py]"]
end

subgraph group_vault["Secret vault"]
  node_secret_management["Encrypted secret CRUD"]
end

node_client(("API client"))
node_redis_service[("Redis service")]

node_client -->|"sends requests"| node_application
node_application -->|"mounts routes"| node_router
node_router -->|"dispatches auth"| node_auth_routes
node_router -->|"dispatches health"| node_health
node_router -->|"dispatches readiness"| node_readiness
node_auth_routes -->|"validates and responds"| node_schemas
node_auth_routes -->|"registers users"| node_auth_services
node_auth_routes -->|"authenticates users"| node_login_service
node_auth_routes -->|"rotates tokens"| node_refresh_service
node_auth_routes -->|"revokes sessions"| node_logout_service
node_auth_routes -->|"enforces quotas"| node_rate_limiting
node_auth_routes -->|"requests database session"| node_db_session
node_auth_services -->|"stores users"| node_users_repo
node_login_service -->|"looks up users"| node_users_repo
node_login_service -->|"creates sessions"| node_sessions_repo
node_login_service -->|"stores refresh tokens"| node_refresh_repo
node_login_service -->|"creates access tokens"| node_token_security
node_login_service -->|"creates refresh tokens"| node_refresh_security
node_refresh_service -->|"checks and rotates"| node_refresh_repo
node_refresh_service -->|"locks session"| node_sessions_repo
node_refresh_service -->|"checks account"| node_users_repo
node_refresh_service -->|"creates access tokens"| node_token_security
node_refresh_service -->|"hashes tokens"| node_refresh_security
node_logout_service -->|"revokes tokens"| node_refresh_repo
node_logout_service -->|"revokes session"| node_sessions_repo
node_auth_dependency -->|"decodes access tokens"| node_token_security
node_auth_dependency -->|"checks session"| node_sessions_repo
node_auth_dependency -->|"checks user"| node_users_repo
node_users_repo -->|"queries user model"| node_models
node_sessions_repo -->|"queries session model"| node_models
node_refresh_repo -->|"queries token model"| node_models
node_db_session -->|"uses database URL"| node_configuration
node_db_session -.->|"opens database sessions"| node_postgres
node_rate_limiting -->|"uses limiter pool"| node_redis
node_redis -.->|"connects to"| node_redis_service
node_readiness -->|"checks database"| node_db_session
node_readiness -->|"checks Redis"| node_redis
node_application -->|"installs middleware"| node_middleware
node_middleware -->|"emits request logs"| node_request_logging
node_middleware -.->|"uses settings"| node_configuration
node_client -.->|"manages owned secrets"| node_secret_management
node_secret_management -.->|"stores encrypted content"| node_postgres
node_secret_management -.->|"uses encryption keyring"| node_configuration

click node_application "https://github.com/iyed523/securevault/blob/main/app/main.py"
click node_router "https://github.com/iyed523/securevault/blob/main/app/api/router.py"
click node_auth_routes "https://github.com/iyed523/securevault/blob/main/app/api/routes/auth.py"
click node_health "https://github.com/iyed523/securevault/blob/main/app/api/routes/health.py"
click node_readiness "https://github.com/iyed523/securevault/blob/main/app/api/routes/ready.py"
click node_schemas "https://github.com/iyed523/securevault/blob/main/app/schemas/auth.py"
click node_auth_services "https://github.com/iyed523/securevault/blob/main/app/services/registration.py"
click node_login_service "https://github.com/iyed523/securevault/blob/main/app/services/login.py"
click node_refresh_service "https://github.com/iyed523/securevault/blob/main/app/services/refresh.py"
click node_logout_service "https://github.com/iyed523/securevault/blob/main/app/services/logout.py"
click node_auth_dependency "https://github.com/iyed523/securevault/blob/main/app/api/dependencies.py"
click node_token_security "https://github.com/iyed523/securevault/blob/main/app/security/tokens.py"
click node_refresh_security "https://github.com/iyed523/securevault/blob/main/app/security/refresh_tokens.py"
click node_rate_limiting "https://github.com/iyed523/securevault/blob/main/app/security/rate_limit.py"
click node_users_repo "https://github.com/iyed523/securevault/blob/main/app/repositories/users.py"
click node_sessions_repo "https://github.com/iyed523/securevault/blob/main/app/repositories/sessions.py"
click node_refresh_repo "https://github.com/iyed523/securevault/blob/main/app/repositories/refresh_tokens.py"
click node_models "https://github.com/iyed523/securevault/blob/main/app/models/session.py"
click node_db_session "https://github.com/iyed523/securevault/blob/main/app/db/session.py"
click node_redis "https://github.com/iyed523/securevault/blob/main/app/infrastructure/redis.py"
click node_readiness_check "https://github.com/iyed523/securevault/blob/main/app/infrastructure/readiness.py"
click node_middleware "https://github.com/iyed523/securevault/blob/main/app/api/middleware.py"
click node_request_logging "https://github.com/iyed523/securevault/blob/main/app/core/logging.py"
click node_configuration "https://github.com/iyed523/securevault/blob/main/app/core/config.py"
click node_secret_management "https://github.com/iyed523/securevault/tree/main/app"

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_application,node_router,node_auth_routes,node_health,node_readiness,node_schemas,node_client toneBlue
class node_auth_services,node_login_service,node_refresh_service,node_logout_service,node_auth_dependency,node_token_security,node_refresh_security,node_rate_limiting,node_redis_service toneAmber
class node_users_repo,node_sessions_repo,node_refresh_repo,node_models,node_db_session,node_postgres toneMint
class node_redis,node_readiness_check,node_middleware,node_request_logging,node_configuration toneRose
class node_secret_management toneIndigo
```

## Components

### HTTP API

- [FastAPI application](https://github.com/iyed523/securevault/blob/main/app/main.py): `app/main.py`
- [API router](https://github.com/iyed523/securevault/blob/main/app/api/router.py): `app/api/router.py`
- [Auth endpoints](https://github.com/iyed523/securevault/blob/main/app/api/routes/auth.py): `app/api/routes/auth.py`
- [Health endpoint](https://github.com/iyed523/securevault/blob/main/app/api/routes/health.py): `app/api/routes/health.py`
- [Readiness endpoint](https://github.com/iyed523/securevault/blob/main/app/api/routes/ready.py): `app/api/routes/ready.py`
- [Auth and user contracts](https://github.com/iyed523/securevault/blob/main/app/schemas/auth.py): `app/schemas/auth.py`

### Identity and security

- [Registration and login](https://github.com/iyed523/securevault/blob/main/app/services/registration.py): `app/services/registration.py`
- [Login flow](https://github.com/iyed523/securevault/blob/main/app/services/login.py): `app/services/login.py`
- [Refresh and replay control](https://github.com/iyed523/securevault/blob/main/app/services/refresh.py): `app/services/refresh.py`
- [Session logout](https://github.com/iyed523/securevault/blob/main/app/services/logout.py): `app/services/logout.py`
- [Request authentication](https://github.com/iyed523/securevault/blob/main/app/api/dependencies.py): `app/api/dependencies.py`
- [JWT access tokens](https://github.com/iyed523/securevault/blob/main/app/security/tokens.py): `app/security/tokens.py`
- [Refresh-token primitives](https://github.com/iyed523/securevault/blob/main/app/security/refresh_tokens.py): `app/security/refresh_tokens.py`
- [Rate limiting](https://github.com/iyed523/securevault/blob/main/app/security/rate_limit.py): `app/security/rate_limit.py`

### Persistence

- [User repository](https://github.com/iyed523/securevault/blob/main/app/repositories/users.py): `app/repositories/users.py`
- [Session repository](https://github.com/iyed523/securevault/blob/main/app/repositories/sessions.py): `app/repositories/sessions.py`
- [Refresh-token repository](https://github.com/iyed523/securevault/blob/main/app/repositories/refresh_tokens.py): `app/repositories/refresh_tokens.py`
- [User and session models](https://github.com/iyed523/securevault/blob/main/app/models/session.py): `app/models/session.py`
- [Database sessions](https://github.com/iyed523/securevault/blob/main/app/db/session.py): `app/db/session.py`
- **PostgreSQL**

### Runtime infrastructure

- [Redis pool](https://github.com/iyed523/securevault/blob/main/app/infrastructure/redis.py): `app/infrastructure/redis.py`
- [Dependency readiness](https://github.com/iyed523/securevault/blob/main/app/infrastructure/readiness.py): `app/infrastructure/readiness.py`
- [Request middleware](https://github.com/iyed523/securevault/blob/main/app/api/middleware.py): `app/api/middleware.py`
- [Structured logging](https://github.com/iyed523/securevault/blob/main/app/core/logging.py): `app/core/logging.py`
- [Runtime configuration](https://github.com/iyed523/securevault/blob/main/app/core/config.py): `app/core/config.py`

### Secret vault

- [Encrypted secret CRUD](https://github.com/iyed523/securevault/tree/main/app): `app`

### Other components

- **API client**
- **Redis service**

## Connections

- API client → FastAPI application: sends requests
- FastAPI application → API router: mounts routes (evidence: `app/main.py`)
- API router → Auth endpoints: dispatches auth (evidence: `app/api/router.py`)
- API router → Health endpoint: dispatches health (evidence: `app/api/router.py`)
- API router → Readiness endpoint: dispatches readiness (evidence: `app/api/router.py`)
- Auth endpoints → Auth and user contracts: validates and responds (evidence: `app/api/routes/auth.py`)
- Auth endpoints → Registration and login: registers users (evidence: `app/api/routes/auth.py`)
- Auth endpoints → Login flow: authenticates users (evidence: `app/api/routes/auth.py`)
- Auth endpoints → Refresh and replay control: rotates tokens (evidence: `app/api/routes/auth.py`)
- Auth endpoints → Session logout: revokes sessions (evidence: `app/api/routes/auth.py`)
- Auth endpoints → Rate limiting: enforces quotas (evidence: `app/api/routes/auth.py`)
- Auth endpoints → Database sessions: requests database session (evidence: `app/api/routes/auth.py`)
- Registration and login → User repository: stores users (evidence: `app/services/registration.py`)
- Login flow → User repository: looks up users (evidence: `app/services/login.py`)
- Login flow → Session repository: creates sessions (evidence: `app/services/login.py`)
- Login flow → Refresh-token repository: stores refresh tokens (evidence: `app/services/login.py`)
- Login flow → JWT access tokens: creates access tokens (evidence: `app/services/login.py`)
- Login flow → Refresh-token primitives: creates refresh tokens (evidence: `app/services/login.py`)
- Refresh and replay control → Refresh-token repository: checks and rotates (evidence: `app/services/refresh.py`)
- Refresh and replay control → Session repository: locks session (evidence: `app/services/refresh.py`)
- Refresh and replay control → User repository: checks account (evidence: `app/services/refresh.py`)
- Refresh and replay control → JWT access tokens: creates access tokens (evidence: `app/services/refresh.py`)
- Refresh and replay control → Refresh-token primitives: hashes tokens (evidence: `app/services/refresh.py`)
- Session logout → Refresh-token repository: revokes tokens (evidence: `app/services/logout.py`)
- Session logout → Session repository: revokes session (evidence: `app/services/logout.py`)
- Request authentication → JWT access tokens: decodes access tokens (evidence: `app/api/dependencies.py`)
- Request authentication → Session repository: checks session
- Request authentication → User repository: checks user
- User repository → User and session models: queries user model (evidence: `app/repositories/users.py`)
- Session repository → User and session models: queries session model (evidence: `app/repositories/sessions.py`)
- Refresh-token repository → User and session models: queries token model (evidence: `app/repositories/refresh_tokens.py`)
- Database sessions → Runtime configuration: uses database URL (evidence: `app/db/session.py`)
- Database sessions → PostgreSQL: opens database sessions
- Rate limiting → Redis pool: uses limiter pool (evidence: `app/api/rate_limit.py`)
- Redis pool → Redis service: connects to
- Readiness endpoint → Database sessions: checks database (evidence: `app/api/routes/ready.py`)
- Readiness endpoint → Redis pool: checks Redis (evidence: `app/api/routes/ready.py`)
- FastAPI application → Request middleware: installs middleware (evidence: `app/main.py`)
- Request middleware → Structured logging: emits request logs (evidence: `app/api/middleware.py`)
- Request middleware → Runtime configuration: uses settings
- API client → Encrypted secret CRUD: manages owned secrets
- Encrypted secret CRUD → PostgreSQL: stores encrypted content
- Encrypted secret CRUD → Runtime configuration: uses encryption keyring (evidence: `app/main.py`)
