# tanmay-sharma-01/digivault architecture

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

- Interactive diagram: https://gitdiagram.com/tanmay-sharma-01/digivault
- Repository: https://github.com/tanmay-sharma-01/digivault

## Overview

#### Purpose and Entry Points
Digital Vault is a same-origin Flask/vanilla-JS secure-notes application. `backend/app.py` starts the HTTP server, exposes the `/api/*` surface, and serves `frontend/index.html` at `/`. The frontend can alternatively be opened directly and target the backend API.

#### Client/API Boundary
`frontend/index.html` is the single-page client: it manages registration/login state, holds the returned session token, sends it as `X-Session-Token`, and drives note CRUD, search, export, logout, and inactivity UI. `backend/app.py` is the API orchestration boundary: request validation, authentication gating, response/status handling, and calls into security and persistence modules.

#### Identity and Login Protection
Registration and login flow through `backend/app.py` and `backend/auth.py`. Auth enforces alphanumeric usernames and password complexity, hashes/checks passwords with bcrypt, and calculates password-strength feedback. User records track failed attempts and `locked_until`; three failed logins lock an account for five minutes. Successful login creates a session rather than exposing credentials.

#### Session Lifecycle
`backend/sessions.py` owns UUID token creation, lookup, refresh, removal, and the two-minute inactivity rule. Protected API routes in `backend/app.py` validate `X-Session-Token` before accessing notes. The client pings the session endpoint periodically and resets to login on expiry; server-side validation remains authoritative.

#### Note Isolation and Encryption
Authenticated note operations are orchestrated in `backend/app.py`. A validated session resolves one username, and all note reads, writes, deletes, searches, and exports operate only within that user’s record. `backend/encryption.py` loads or creates a Fernet key and encrypts note content before persistence; normal note reads decrypt content for the authenticated response. Titles and note metadata remain available for title-based search.

#### Persistence and Runtime State
`backend/storage.py` provides JSON-file persistence for users and sessions. Runtime data resides under `data/`: users (password hashes, lock state, encrypted notes), active sessions, and the Fernet key are created on demand and excluded from source control. This is local filesystem storage rather than a database, with no indicated multi-process coordination or transactional boundary.

#### Runtime and External Dependencies
The application runs on Python/Flask with `backend/requirements.txt`; Flask-CORS enables browser access, bcrypt supplies password hashing, and `cryptography` supplies Fernet encryption. There are no remote services or database dependencies. The security boundary assumes local protection of `data/secret.key`; compromise of that key permits decryption of stored note bodies.

Main entry points: [`backend/app.py`](https://github.com/tanmay-sharma-01/digivault/blob/main/backend/app.py) (HTTP server and API), [`backend/storage.py`](https://github.com/tanmay-sharma-01/digivault/blob/main/backend/storage.py) (JSON persistence), [`backend/auth.py`](https://github.com/tanmay-sharma-01/digivault/blob/main/backend/auth.py) (Authentication), [`backend/encryption.py`](https://github.com/tanmay-sharma-01/digivault/blob/main/backend/encryption.py) (Note encryption)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser Client"]
  node_spa["Single-page client<br/>vanilla JS UI<br/>[index.html]"]
end

subgraph group_api["Flask Backend"]
  node_server["HTTP server and API<br/>Flask app<br/>[app.py]"]
  node_flask{{"Flask runtime<br/>Python dependency<br/>[requirements.txt]"}}
  node_cors{{"Flask-CORS<br/>browser access dependency<br/>[requirements.txt]"}}
end

subgraph group_security["Security Services"]
  node_auth["Authentication<br/>credential security<br/>[auth.py]"]
  node_sessions["Session manager<br/>token lifecycle<br/>[sessions.py]"]
  node_encryption["Note encryption<br/>Fernet crypto<br/>[encryption.py]"]
  node_bcrypt{{"bcrypt<br/>password hashing dependency<br/>[requirements.txt]"}}
  node_cryptography{{"cryptography<br/>Fernet dependency<br/>[requirements.txt]"}}
end

subgraph group_storage["Local Runtime Data"]
  node_persistence["JSON persistence<br/>filesystem store<br/>[storage.py]"]
  node_users_data[("User records and notes<br/>JSON data")]
  node_session_data[("Active sessions<br/>JSON data")]
  node_fernet_key["Fernet key<br/>secret key file"]
end

node_spa -->|"HTTP /api/* + X-Session-Token"| node_server
node_server -->|"serves /"| node_spa
node_server -->|"registration and login"| node_auth
node_server -->|"protects routes; refreshes and removes sessions"| node_sessions
node_server -->|"user-isolated note CRUD, search, export"| node_persistence
node_server -->|"encrypts writes; decrypts reads"| node_encryption
node_auth -->|"stores credentials and lock state"| node_persistence
node_sessions -->|"stores active tokens"| node_persistence
node_encryption -->|"loads or creates key"| node_fernet_key
node_persistence -->|"persists users and encrypted notes"| node_users_data
node_persistence -->|"persists sessions"| node_session_data
node_server -.->|"runs on"| node_flask
node_server -.->|"enables browser access"| node_cors
node_auth -.->|"hashes and verifies passwords"| node_bcrypt
node_encryption -.->|"provides Fernet"| node_cryptography

click node_spa "https://github.com/tanmay-sharma-01/digivault/blob/main/frontend/index.html"
click node_server "https://github.com/tanmay-sharma-01/digivault/blob/main/backend/app.py"
click node_auth "https://github.com/tanmay-sharma-01/digivault/blob/main/backend/auth.py"
click node_sessions "https://github.com/tanmay-sharma-01/digivault/blob/main/backend/sessions.py"
click node_encryption "https://github.com/tanmay-sharma-01/digivault/blob/main/backend/encryption.py"
click node_persistence "https://github.com/tanmay-sharma-01/digivault/blob/main/backend/storage.py"
click node_flask "https://github.com/tanmay-sharma-01/digivault/blob/main/backend/requirements.txt"
click node_cors "https://github.com/tanmay-sharma-01/digivault/blob/main/backend/requirements.txt"
click node_bcrypt "https://github.com/tanmay-sharma-01/digivault/blob/main/backend/requirements.txt"
click node_cryptography "https://github.com/tanmay-sharma-01/digivault/blob/main/backend/requirements.txt"

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_spa toneBlue
class node_server,node_flask,node_cors toneAmber
class node_auth,node_sessions,node_encryption,node_bcrypt,node_cryptography toneMint
class node_persistence,node_users_data,node_session_data,node_fernet_key toneRose
```

## Components

### Browser Client

- [Single-page client](https://github.com/tanmay-sharma-01/digivault/blob/main/frontend/index.html): vanilla JS UI · Manages login state, note actions, inactivity UI, and session token. · `frontend/index.html`

### Flask Backend

- [HTTP server and API](https://github.com/tanmay-sharma-01/digivault/blob/main/backend/app.py): Flask app · Serves the client and orchestrates validation, auth, note operations, and responses. · `backend/app.py`
- [Flask runtime](https://github.com/tanmay-sharma-01/digivault/blob/main/backend/requirements.txt): Python dependency · `backend/requirements.txt`
- [Flask-CORS](https://github.com/tanmay-sharma-01/digivault/blob/main/backend/requirements.txt): browser access dependency · `backend/requirements.txt`

### Security Services

- [Authentication](https://github.com/tanmay-sharma-01/digivault/blob/main/backend/auth.py): credential security · Validates credentials, bcrypt hashes/checks passwords, and enforces login lockouts. · `backend/auth.py`
- [Session manager](https://github.com/tanmay-sharma-01/digivault/blob/main/backend/sessions.py): token lifecycle · Creates, validates, refreshes, and expires UUID sessions after two minutes of inactivity. · `backend/sessions.py`
- [Note encryption](https://github.com/tanmay-sharma-01/digivault/blob/main/backend/encryption.py): Fernet crypto · Encrypts persisted note bodies and decrypts authenticated reads. · `backend/encryption.py`
- [bcrypt](https://github.com/tanmay-sharma-01/digivault/blob/main/backend/requirements.txt): password hashing dependency · `backend/requirements.txt`
- [cryptography](https://github.com/tanmay-sharma-01/digivault/blob/main/backend/requirements.txt): Fernet dependency · `backend/requirements.txt`

### Local Runtime Data

On-demand JSON state and a locally protected encryption key.

- [JSON persistence](https://github.com/tanmay-sharma-01/digivault/blob/main/backend/storage.py): filesystem store · Reads and writes users and active session records. · `backend/storage.py`
- **User records and notes**: JSON data · Contains password hashes, lock state, and user-isolated encrypted notes.
- **Active sessions**: JSON data
- **Fernet key**: secret key file · Compromise permits decryption of stored note bodies.

## Connections

- Single-page client → HTTP server and API: HTTP /api/* + X-Session-Token
- HTTP server and API → Single-page client: serves /
- HTTP server and API → Authentication: registration and login
- HTTP server and API → Session manager: protects routes; refreshes and removes sessions
- HTTP server and API → JSON persistence: user-isolated note CRUD, search, export
- HTTP server and API → Note encryption: encrypts writes; decrypts reads
- Authentication → JSON persistence: stores credentials and lock state
- Session manager → JSON persistence: stores active tokens
- Note encryption → Fernet key: loads or creates key
- JSON persistence → User records and notes: persists users and encrypted notes
- JSON persistence → Active sessions: persists sessions
- HTTP server and API → Flask runtime: runs on
- HTTP server and API → Flask-CORS: enables browser access
- Authentication → bcrypt: hashes and verifies passwords
- Note encryption → cryptography: provides Fernet