# shikhar0x/cloudvault architecture

> Architecture diagram of the GitHub repository shikhar0x/cloudvault, 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/shikhar0x/cloudvault
- Repository: https://github.com/shikhar0x/cloudvault

## Overview

CloudVault is a self-hosted file storage and sharing product. Users enter through the Next.js dashboard or account pages, then use the REST API to authenticate, organize folders, upload and download files, create expiring public links, and check storage usage. The backend separates route handling from domain services, with PostgreSQL metadata and a provider-based object-storage layer. The README documents the broader frontend capabilities; source excerpts show backend registration and selected service calls, so unsampled frontend-to-API details are represented only at the documented boundary.

Main entry points: [`backend/app/main.py`](https://github.com/shikhar0x/cloudvault/blob/main/backend/app/main.py) (FastAPI application), [`backend/app/core/dependencies.py`](https://github.com/shikhar0x/cloudvault/blob/main/backend/app/core/dependencies.py) (JWT and ownership), [`backend/app/database/models/folder.py`](https://github.com/shikhar0x/cloudvault/blob/main/backend/app/database/models/folder.py) (SQLAlchemy models), [`backend/app/infrastructure/storage/interface.py`](https://github.com/shikhar0x/cloudvault/blob/main/backend/app/infrastructure/storage/interface.py) (Storage provider interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web application"]
  node_dashboard["File explorer<br/>[page.tsx]"]
  node_account["Login and registration<br/>[page.tsx]"]
  node_sharepage["Public share portal<br/>[page.tsx]"]
  node_apiclient["API client<br/>[api.ts]"]
end

subgraph group_api["API entry and routes"]
  node_app["FastAPI application<br/>[main.py]"]
  node_authroutes["Authentication routes<br/>[router.py]"]
  node_fileroutes["File routes<br/>[router.py]"]
  node_folderroutes["Folder routes<br/>[router.py]"]
  node_shareroutes["Sharing routes<br/>[router.py]"]
  node_storageroutes["Quota routes<br/>[router.py]"]
end

subgraph group_domain["Domain services"]
  node_authservice["Authentication service<br/>[service.py]"]
  node_fileservice["File management<br/>[service.py]"]
  node_folderservice["Folder hierarchy<br/>[service.py]"]
  node_shareservice["Share links<br/>[service.py]"]
  node_quotaservice["Usage calculation<br/>[service.py]"]
end

subgraph group_security["Identity and access"]
  node_access["JWT and ownership<br/>[dependencies.py]"]
  node_security["Password and token primitives<br/>[security.py]"]
end

subgraph group_data["Persistence and storage"]
  node_sessions["Database sessions<br/>[session.py]"]
  node_models["SQLAlchemy models<br/>[folder.py]"]
  node_provider["Storage provider interface<br/>[interface.py]"]
  node_local["Local storage<br/>[local.py]"]
  node_s3["S3 storage<br/>[s3.py]"]
end

node_user(("User"))
node_postgres[("PostgreSQL")]
node_objects[("Object storage")]

node_user -->|"manages files"| node_dashboard
node_user -->|"signs in"| node_account
node_user -->|"opens share"| node_sharepage
node_dashboard -.->|"uses API"| node_apiclient
node_account -.->|"uses API"| node_apiclient
node_sharepage -.->|"uses API"| node_apiclient
node_apiclient -->|"REST requests"| node_app
node_app -->|"registers"| node_authroutes
node_app -->|"registers"| node_fileroutes
node_app -->|"registers"| node_folderroutes
node_app -->|"registers"| node_shareroutes
node_app -->|"registers"| node_storageroutes
node_authroutes -->|"calls"| node_authservice
node_fileroutes -->|"calls"| node_fileservice
node_folderroutes -->|"calls"| node_folderservice
node_shareroutes -->|"calls"| node_shareservice
node_storageroutes -->|"calls"| node_quotaservice
node_authroutes -->|"requires identity"| node_access
node_fileroutes -->|"requires identity"| node_access
node_folderroutes -->|"requires identity"| node_access
node_shareroutes -->|"protects creation"| node_access
node_access -->|"validates token"| node_security
node_access -->|"loads user"| node_sessions
node_authservice -->|"hashes and signs"| node_security
node_authservice -->|"reads and writes users"| node_models
node_fileservice -->|"reads and writes files"| node_models
node_folderservice -->|"reads and writes folders"| node_models
node_folderservice -->|"deletes objects"| node_provider
node_shareservice -->|"reads and writes links"| node_models
node_shareservice -->|"resolves provider"| node_provider
node_quotaservice -->|"reads usage data"| node_models
node_provider -->|"selects backend"| node_local
node_provider -->|"selects backend"| node_s3
node_fileservice -->|"stores and streams"| node_provider
node_sessions -->|"opens sessions"| node_postgres
node_models -->|"maps records"| node_postgres
node_local -.->|"reads and writes"| node_objects
node_s3 -.->|"reads and writes"| node_objects

click node_dashboard "https://github.com/shikhar0x/cloudvault/blob/main/frontend/src/app/page.tsx"
click node_account "https://github.com/shikhar0x/cloudvault/blob/main/frontend/src/app/login/page.tsx"
click node_sharepage "https://github.com/shikhar0x/cloudvault/blob/main/frontend/src/app/share/%5Btoken%5D/page.tsx"
click node_apiclient "https://github.com/shikhar0x/cloudvault/blob/main/frontend/src/lib/api.ts"
click node_app "https://github.com/shikhar0x/cloudvault/blob/main/backend/app/main.py"
click node_authroutes "https://github.com/shikhar0x/cloudvault/blob/main/backend/app/modules/auth/router.py"
click node_fileroutes "https://github.com/shikhar0x/cloudvault/blob/main/backend/app/modules/files/router.py"
click node_folderroutes "https://github.com/shikhar0x/cloudvault/blob/main/backend/app/modules/folders/router.py"
click node_shareroutes "https://github.com/shikhar0x/cloudvault/blob/main/backend/app/modules/sharing/router.py"
click node_storageroutes "https://github.com/shikhar0x/cloudvault/blob/main/backend/app/modules/storage/router.py"
click node_authservice "https://github.com/shikhar0x/cloudvault/blob/main/backend/app/modules/auth/service.py"
click node_fileservice "https://github.com/shikhar0x/cloudvault/blob/main/backend/app/modules/files/service.py"
click node_folderservice "https://github.com/shikhar0x/cloudvault/blob/main/backend/app/modules/folders/service.py"
click node_shareservice "https://github.com/shikhar0x/cloudvault/blob/main/backend/app/modules/sharing/service.py"
click node_quotaservice "https://github.com/shikhar0x/cloudvault/blob/main/backend/app/modules/storage/service.py"
click node_access "https://github.com/shikhar0x/cloudvault/blob/main/backend/app/core/dependencies.py"
click node_security "https://github.com/shikhar0x/cloudvault/blob/main/backend/app/core/security.py"
click node_sessions "https://github.com/shikhar0x/cloudvault/blob/main/backend/app/database/session.py"
click node_models "https://github.com/shikhar0x/cloudvault/blob/main/backend/app/database/models/folder.py"
click node_provider "https://github.com/shikhar0x/cloudvault/blob/main/backend/app/infrastructure/storage/interface.py"
click node_local "https://github.com/shikhar0x/cloudvault/blob/main/backend/app/infrastructure/storage/local.py"
click node_s3 "https://github.com/shikhar0x/cloudvault/blob/main/backend/app/infrastructure/storage/s3.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_dashboard,node_account,node_sharepage,node_apiclient,node_user toneBlue
class node_app,node_authroutes,node_fileroutes,node_folderroutes,node_shareroutes,node_storageroutes,node_postgres,node_objects toneAmber
class node_authservice,node_fileservice,node_folderservice,node_shareservice,node_quotaservice toneMint
class node_access,node_security toneRose
class node_sessions,node_models,node_provider,node_local,node_s3 toneIndigo
```

## Components

### Web application

- [File explorer](https://github.com/shikhar0x/cloudvault/blob/main/frontend/src/app/page.tsx): `frontend/src/app/page.tsx`
- [Login and registration](https://github.com/shikhar0x/cloudvault/blob/main/frontend/src/app/login/page.tsx): `frontend/src/app/login/page.tsx`
- [Public share portal](https://github.com/shikhar0x/cloudvault/blob/main/frontend/src/app/share/%5Btoken%5D/page.tsx): `frontend/src/app/share/[token]/page.tsx`
- [API client](https://github.com/shikhar0x/cloudvault/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`

### API entry and routes

- [FastAPI application](https://github.com/shikhar0x/cloudvault/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication routes](https://github.com/shikhar0x/cloudvault/blob/main/backend/app/modules/auth/router.py): `backend/app/modules/auth/router.py`
- [File routes](https://github.com/shikhar0x/cloudvault/blob/main/backend/app/modules/files/router.py): `backend/app/modules/files/router.py`
- [Folder routes](https://github.com/shikhar0x/cloudvault/blob/main/backend/app/modules/folders/router.py): `backend/app/modules/folders/router.py`
- [Sharing routes](https://github.com/shikhar0x/cloudvault/blob/main/backend/app/modules/sharing/router.py): `backend/app/modules/sharing/router.py`
- [Quota routes](https://github.com/shikhar0x/cloudvault/blob/main/backend/app/modules/storage/router.py): `backend/app/modules/storage/router.py`

### Domain services

- [Authentication service](https://github.com/shikhar0x/cloudvault/blob/main/backend/app/modules/auth/service.py): `backend/app/modules/auth/service.py`
- [File management](https://github.com/shikhar0x/cloudvault/blob/main/backend/app/modules/files/service.py): `backend/app/modules/files/service.py`
- [Folder hierarchy](https://github.com/shikhar0x/cloudvault/blob/main/backend/app/modules/folders/service.py): `backend/app/modules/folders/service.py`
- [Share links](https://github.com/shikhar0x/cloudvault/blob/main/backend/app/modules/sharing/service.py): `backend/app/modules/sharing/service.py`
- [Usage calculation](https://github.com/shikhar0x/cloudvault/blob/main/backend/app/modules/storage/service.py): `backend/app/modules/storage/service.py`

### Identity and access

- [JWT and ownership](https://github.com/shikhar0x/cloudvault/blob/main/backend/app/core/dependencies.py): `backend/app/core/dependencies.py`
- [Password and token primitives](https://github.com/shikhar0x/cloudvault/blob/main/backend/app/core/security.py): `backend/app/core/security.py`

### Persistence and storage

- [Database sessions](https://github.com/shikhar0x/cloudvault/blob/main/backend/app/database/session.py): `backend/app/database/session.py`
- [SQLAlchemy models](https://github.com/shikhar0x/cloudvault/blob/main/backend/app/database/models/folder.py): `backend/app/database/models/folder.py`
- [Storage provider interface](https://github.com/shikhar0x/cloudvault/blob/main/backend/app/infrastructure/storage/interface.py): `backend/app/infrastructure/storage/interface.py`
- [Local storage](https://github.com/shikhar0x/cloudvault/blob/main/backend/app/infrastructure/storage/local.py): `backend/app/infrastructure/storage/local.py`
- [S3 storage](https://github.com/shikhar0x/cloudvault/blob/main/backend/app/infrastructure/storage/s3.py): `backend/app/infrastructure/storage/s3.py`

### Other components

- **User**
- **PostgreSQL**
- **Object storage**

## Connections

- User → File explorer: manages files
- User → Login and registration: signs in
- User → Public share portal: opens share
- File explorer → API client: uses API
- Login and registration → API client: uses API
- Public share portal → API client: uses API
- API client → FastAPI application: REST requests
- FastAPI application → Authentication routes: registers (evidence: `backend/app/main.py`)
- FastAPI application → File routes: registers (evidence: `backend/app/main.py`)
- FastAPI application → Folder routes: registers (evidence: `backend/app/main.py`)
- FastAPI application → Sharing routes: registers (evidence: `backend/app/main.py`)
- FastAPI application → Quota routes: registers (evidence: `backend/app/main.py`)
- Authentication routes → Authentication service: calls (evidence: `backend/app/modules/auth/router.py`)
- File routes → File management: calls (evidence: `backend/app/modules/files/router.py`)
- Folder routes → Folder hierarchy: calls (evidence: `backend/app/modules/folders/router.py`)
- Sharing routes → Share links: calls (evidence: `backend/app/modules/sharing/router.py`)
- Quota routes → Usage calculation: calls (evidence: `backend/app/modules/storage/router.py`)
- Authentication routes → JWT and ownership: requires identity (evidence: `backend/app/modules/auth/router.py`)
- File routes → JWT and ownership: requires identity (evidence: `backend/app/modules/files/router.py`)
- Folder routes → JWT and ownership: requires identity (evidence: `backend/app/modules/folders/router.py`)
- Sharing routes → JWT and ownership: protects creation (evidence: `backend/app/modules/sharing/router.py`)
- JWT and ownership → Password and token primitives: validates token (evidence: `backend/app/core/dependencies.py`)
- JWT and ownership → Database sessions: loads user (evidence: `backend/app/core/dependencies.py`)
- Authentication service → Password and token primitives: hashes and signs (evidence: `backend/app/modules/auth/service.py`)
- Authentication service → SQLAlchemy models: reads and writes users (evidence: `backend/app/modules/auth/service.py`)
- File management → SQLAlchemy models: reads and writes files (evidence: `backend/app/modules/files/service.py`)
- Folder hierarchy → SQLAlchemy models: reads and writes folders (evidence: `backend/app/modules/folders/service.py`)
- Folder hierarchy → Storage provider interface: deletes objects (evidence: `backend/app/modules/folders/service.py`)
- Share links → SQLAlchemy models: reads and writes links (evidence: `backend/app/modules/sharing/service.py`)
- Share links → Storage provider interface: resolves provider (evidence: `backend/app/modules/sharing/service.py`)
- Usage calculation → SQLAlchemy models: reads usage data (evidence: `backend/app/modules/storage/service.py`)
- Storage provider interface → Local storage: selects backend (evidence: `backend/app/infrastructure/storage/__init__.py`)
- Storage provider interface → S3 storage: selects backend (evidence: `backend/app/infrastructure/storage/__init__.py`)
- File management → Storage provider interface: stores and streams (evidence: `backend/app/modules/files/service.py`)
- Database sessions → PostgreSQL: opens sessions (evidence: `backend/app/database/session.py`)
- SQLAlchemy models → PostgreSQL: maps records
- Local storage → Object storage: reads and writes
- S3 storage → Object storage: reads and writes
