# hmsmiraz/kesec architecture

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

- Interactive diagram: https://gitdiagram.com/hmsmiraz/kesec
- Repository: https://github.com/hmsmiraz/kesec

## Overview

Kesec is a self-hosted credential vault. The main workflow is account registration or login, followed by authenticated viewing and CRUD of vault entries; users can also generate, reveal, and copy passwords and search entries. The backend separates auth and secret API routes from shared security and persistence layers. The README documents encryption at rest and the UI capabilities; the secrets router and dashboard implementation were not excerpted, so those relationships are limited to documented behavior rather than inferred calls.

Main entry points: [`frontend/app/dashboard/page.tsx`](https://github.com/hmsmiraz/kesec/blob/main/frontend/app/dashboard/page.tsx) (Vault dashboard), [`backend/app/main.py`](https://github.com/hmsmiraz/kesec/blob/main/backend/app/main.py) (FastAPI application), [`backend/app/routers/auth.py`](https://github.com/hmsmiraz/kesec/blob/main/backend/app/routers/auth.py) (Auth routes), [`backend/app/routers/secrets.py`](https://github.com/hmsmiraz/kesec/blob/main/backend/app/routers/secrets.py) (Secret routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Vault interface"]
  node_auth_pages["Login and register<br/>[page.tsx]"]
  node_register_page["Registration page<br/>[page.tsx]"]
  node_auth_context["Session context<br/>[auth.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
  node_dashboard["Vault dashboard<br/>[page.tsx]"]
  node_secret_card["Credential card<br/>[SecretCard.tsx]"]
  node_secret_form["Credential editor"]
  node_password_tools["Password tools"]
end

subgraph group_api["REST API"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_auth_routes["Auth routes<br/>[auth.py]"]
  node_secret_routes["Secret routes<br/>[secrets.py]"]
end

subgraph group_security["Security services"]
  node_auth_deps["Auth dependencies<br/>[deps.py]"]
  node_security_ops["Password and JWT security<br/>[security.py]"]
  node_crypto["Credential encryption<br/>[crypto.py]"]
  node_config["Runtime configuration<br/>[config.py]"]
end

subgraph group_storage["Persistence"]
  node_models["User and vault models<br/>[models.py]"]
  node_database["Database session<br/>[database.py]"]
end

node_user(("Vault user"))

node_user -->|"signs in"| node_auth_pages
node_user -->|"registers"| node_register_page
node_user -->|"manages vault"| node_dashboard
node_auth_context -->|"calls"| node_api_client
node_auth_pages -.->|"uses session"| node_auth_context
node_register_page -.->|"registers through"| node_api_client
node_dashboard -.->|"uses CRUD"| node_api_client
node_dashboard -.->|"shows entries"| node_secret_card
node_dashboard -.->|"edits entries"| node_secret_form
node_dashboard -.->|"generates passwords"| node_password_tools
node_api_client -->|"sends REST requests"| node_api_app
node_api_app -->|"registers router"| node_auth_routes
node_api_app -->|"registers router"| node_secret_routes
node_auth_routes -->|"uses dependencies"| node_auth_deps
node_auth_routes -->|"hashes and signs"| node_security_ops
node_auth_routes -->|"queries and stores"| node_models
node_secret_routes -.->|"authenticates requests"| node_auth_deps
node_secret_routes -.->|"encrypts credentials"| node_crypto
node_secret_routes -.->|"persists entries"| node_models
node_auth_deps -->|"validates tokens"| node_security_ops
node_auth_deps -->|"loads sessions and users"| node_models
node_models -->|"uses ORM base"| node_database
node_api_app -->|"creates tables"| node_database
node_security_ops -->|"reads settings"| node_config
node_crypto -->|"reads key settings"| node_config

click node_auth_pages "https://github.com/hmsmiraz/kesec/blob/main/frontend/app/login/page.tsx"
click node_register_page "https://github.com/hmsmiraz/kesec/blob/main/frontend/app/register/page.tsx"
click node_auth_context "https://github.com/hmsmiraz/kesec/blob/main/frontend/lib/auth.tsx"
click node_api_client "https://github.com/hmsmiraz/kesec/blob/main/frontend/lib/api.ts"
click node_dashboard "https://github.com/hmsmiraz/kesec/blob/main/frontend/app/dashboard/page.tsx"
click node_secret_card "https://github.com/hmsmiraz/kesec/blob/main/frontend/components/SecretCard.tsx"
click node_secret_form "https://github.com/hmsmiraz/kesec/blob/main/frontend/components/SecretFormModal.tsx"
click node_password_tools "https://github.com/hmsmiraz/kesec/blob/main/frontend/lib/generatePassword.ts"
click node_api_app "https://github.com/hmsmiraz/kesec/blob/main/backend/app/main.py"
click node_auth_routes "https://github.com/hmsmiraz/kesec/blob/main/backend/app/routers/auth.py"
click node_secret_routes "https://github.com/hmsmiraz/kesec/blob/main/backend/app/routers/secrets.py"
click node_auth_deps "https://github.com/hmsmiraz/kesec/blob/main/backend/app/deps.py"
click node_security_ops "https://github.com/hmsmiraz/kesec/blob/main/backend/app/security.py"
click node_crypto "https://github.com/hmsmiraz/kesec/blob/main/backend/app/crypto.py"
click node_config "https://github.com/hmsmiraz/kesec/blob/main/backend/app/config.py"
click node_models "https://github.com/hmsmiraz/kesec/blob/main/backend/app/models.py"
click node_database "https://github.com/hmsmiraz/kesec/blob/main/backend/app/database.py"

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_pages,node_register_page,node_auth_context,node_api_client,node_dashboard,node_secret_card,node_secret_form,node_password_tools,node_user toneBlue
class node_api_app,node_auth_routes,node_secret_routes toneAmber
class node_auth_deps,node_security_ops,node_crypto,node_config toneMint
class node_models,node_database toneRose
```

## Components

### Vault interface

- [Login and register](https://github.com/hmsmiraz/kesec/blob/main/frontend/app/login/page.tsx): `frontend/app/login/page.tsx`
- [Registration page](https://github.com/hmsmiraz/kesec/blob/main/frontend/app/register/page.tsx): `frontend/app/register/page.tsx`
- [Session context](https://github.com/hmsmiraz/kesec/blob/main/frontend/lib/auth.tsx): `frontend/lib/auth.tsx`
- [API client](https://github.com/hmsmiraz/kesec/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`
- [Vault dashboard](https://github.com/hmsmiraz/kesec/blob/main/frontend/app/dashboard/page.tsx): `frontend/app/dashboard/page.tsx`
- [Credential card](https://github.com/hmsmiraz/kesec/blob/main/frontend/components/SecretCard.tsx): `frontend/components/SecretCard.tsx`
- [Credential editor](https://github.com/hmsmiraz/kesec/blob/main/frontend/components/SecretFormModal.tsx): `frontend/components/SecretFormModal.tsx`
- [Password tools](https://github.com/hmsmiraz/kesec/blob/main/frontend/lib/generatePassword.ts): `frontend/lib/generatePassword.ts`

### REST API

- [FastAPI application](https://github.com/hmsmiraz/kesec/blob/main/backend/app/main.py): `backend/app/main.py`
- [Auth routes](https://github.com/hmsmiraz/kesec/blob/main/backend/app/routers/auth.py): `backend/app/routers/auth.py`
- [Secret routes](https://github.com/hmsmiraz/kesec/blob/main/backend/app/routers/secrets.py): `backend/app/routers/secrets.py`

### Security services

- [Auth dependencies](https://github.com/hmsmiraz/kesec/blob/main/backend/app/deps.py): `backend/app/deps.py`
- [Password and JWT security](https://github.com/hmsmiraz/kesec/blob/main/backend/app/security.py): `backend/app/security.py`
- [Credential encryption](https://github.com/hmsmiraz/kesec/blob/main/backend/app/crypto.py): `backend/app/crypto.py`
- [Runtime configuration](https://github.com/hmsmiraz/kesec/blob/main/backend/app/config.py): `backend/app/config.py`

### Persistence

- [User and vault models](https://github.com/hmsmiraz/kesec/blob/main/backend/app/models.py): `backend/app/models.py`
- [Database session](https://github.com/hmsmiraz/kesec/blob/main/backend/app/database.py): `backend/app/database.py`

### Other components

- **Vault user**

## Connections

- Vault user → Login and register: signs in (evidence: `README.md`)
- Vault user → Registration page: registers (evidence: `README.md`)
- Vault user → Vault dashboard: manages vault (evidence: `README.md`)
- Session context → API client: calls (evidence: `frontend/lib/auth.tsx`)
- Login and register → Session context: uses session
- Registration page → API client: registers through
- Vault dashboard → API client: uses CRUD
- Vault dashboard → Credential card: shows entries
- Vault dashboard → Credential editor: edits entries
- Vault dashboard → Password tools: generates passwords
- API client → FastAPI application: sends REST requests (evidence: `README.md`)
- FastAPI application → Auth routes: registers router (evidence: `backend/app/main.py`)
- FastAPI application → Secret routes: registers router (evidence: `backend/app/main.py`)
- Auth routes → Auth dependencies: uses dependencies (evidence: `backend/app/routers/auth.py`)
- Auth routes → Password and JWT security: hashes and signs (evidence: `backend/app/routers/auth.py`)
- Auth routes → User and vault models: queries and stores (evidence: `backend/app/routers/auth.py`)
- Secret routes → Auth dependencies: authenticates requests
- Secret routes → Credential encryption: encrypts credentials
- Secret routes → User and vault models: persists entries
- Auth dependencies → Password and JWT security: validates tokens (evidence: `backend/app/deps.py`)
- Auth dependencies → User and vault models: loads sessions and users (evidence: `backend/app/deps.py`)
- User and vault models → Database session: uses ORM base (evidence: `backend/app/models.py`)
- FastAPI application → Database session: creates tables (evidence: `backend/app/main.py`)
- Password and JWT security → Runtime configuration: reads settings (evidence: `backend/app/security.py`)
- Credential encryption → Runtime configuration: reads key settings (evidence: `backend/app/crypto.py`)
