# aswina1636/home-server architecture

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

- Interactive diagram: https://gitdiagram.com/aswina1636/home-server
- Repository: https://github.com/aswina1636/home-server

## Overview

HomeServer is a private cloud file manager and video streamer, with user and administrator workflows. Users sign up or log in, then browse, search, upload, download, and view files; administrators manage accounts, quota requests, messages, devices, deletion requests, settings, and audit history. React pages call a FastAPI service, whose routes use authentication, file/admin logic, and SQLAlchemy models and database access. The README documents security controls, password recovery, streaming, and admin features; some subsystem links are based on documentation or the source index rather than sampled route code.

Main entry points: [`backend/files.py`](https://github.com/aswina1636/home-server/blob/main/backend/files.py) (File routes), [`backend/main.py`](https://github.com/aswina1636/home-server/blob/main/backend/main.py) (FastAPI routes), [`backend/auth.py`](https://github.com/aswina1636/home-server/blob/main/backend/auth.py) (Auth routes), [`frontend/src/api.js`](https://github.com/aswina1636/home-server/blob/main/frontend/src/api.js) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_app["App routing<br/>[App.jsx]"]
  node_authui["Auth state<br/>[AuthContext.jsx]"]
  node_api["API client<br/>[api.js]"]
  node_dashboard["File dashboard<br/>[Dashboard.jsx]"]
  node_fileviews["File views<br/>[FileGrid.jsx]"]
  node_fileutils["File utilities<br/>[fileUtils.js]"]
  node_viewer["Media viewer<br/>[FileViewer.jsx]"]
  node_player["Video player<br/>[VideoPlayer.jsx]"]
end

subgraph group_identity["Identity and security"]
  node_authroutes["Auth routes<br/>[auth.py]"]
  node_middleware["Security middleware<br/>[middleware.py]"]
  node_models["Domain models<br/>[models.py]"]
  node_database[("SQL database access<br/>[database.py]")]
end

subgraph group_files["File and media"]
  node_filesroutes["File routes<br/>[files.py]"]
  node_disk[("File storage")]
end

subgraph group_admin["Administration"]
  node_adminui["Admin pages"]
  node_storageui["Storage requests"]
  node_adminroutes["Admin routes<br/>[admin.py]"]
end

node_person(("User or admin"))
node_service{{"FastAPI routes<br/>[main.py]"}}

node_person -->|"uses"| node_app
node_app -->|"provides auth"| node_authui
node_app -->|"routes to"| node_dashboard
node_app -->|"routes to"| node_adminui
node_authui -->|"checks profile"| node_api
node_dashboard -->|"requests files"| node_api
node_dashboard -->|"renders"| node_fileviews
node_fileviews -->|"uses"| node_fileutils
node_dashboard -.->|"opens files"| node_viewer
node_viewer -->|"embeds"| node_player
node_adminui -->|"requests admin data"| node_api
node_storageui -->|"submits decisions"| node_api
node_api -->|"calls HTTP API"| node_service
node_service -->|"routes auth"| node_authroutes
node_service -->|"routes files"| node_filesroutes
node_service -->|"routes admin"| node_adminroutes
node_service -->|"configures"| node_middleware
node_authroutes -->|"queries users"| node_models
node_authroutes -->|"gets sessions"| node_database
node_filesroutes -->|"uses records"| node_models
node_filesroutes -->|"gets sessions"| node_database
node_filesroutes -->|"checks identity"| node_authroutes
node_filesroutes -.->|"reads and writes"| node_disk
node_adminroutes -->|"uses records"| node_models
node_adminroutes -->|"gets sessions"| node_database
node_adminroutes -->|"checks admins"| node_authroutes
node_models -->|"declares tables"| node_database

click node_app "https://github.com/aswina1636/home-server/blob/main/frontend/src/App.jsx"
click node_authui "https://github.com/aswina1636/home-server/blob/main/frontend/src/contexts/AuthContext.jsx"
click node_api "https://github.com/aswina1636/home-server/blob/main/frontend/src/api.js"
click node_dashboard "https://github.com/aswina1636/home-server/blob/main/frontend/src/pages/Dashboard.jsx"
click node_fileviews "https://github.com/aswina1636/home-server/blob/main/frontend/src/components/FileGrid.jsx"
click node_fileutils "https://github.com/aswina1636/home-server/blob/main/frontend/src/utils/fileUtils.js"
click node_viewer "https://github.com/aswina1636/home-server/blob/main/frontend/src/components/FileViewer.jsx"
click node_player "https://github.com/aswina1636/home-server/blob/main/frontend/src/components/VideoPlayer.jsx"
click node_adminui "https://github.com/aswina1636/home-server/tree/main/frontend/src/pages/admin"
click node_storageui "https://github.com/aswina1636/home-server/blob/main/frontend/src/pages/admin/AdminStorageRequests.jsx"
click node_authroutes "https://github.com/aswina1636/home-server/blob/main/backend/auth.py"
click node_filesroutes "https://github.com/aswina1636/home-server/blob/main/backend/files.py"
click node_adminroutes "https://github.com/aswina1636/home-server/blob/main/backend/admin.py"
click node_service "https://github.com/aswina1636/home-server/blob/main/backend/main.py"
click node_middleware "https://github.com/aswina1636/home-server/blob/main/backend/middleware.py"
click node_models "https://github.com/aswina1636/home-server/blob/main/backend/models.py"
click node_database "https://github.com/aswina1636/home-server/blob/main/backend/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_app,node_authui,node_api,node_dashboard,node_fileviews,node_fileutils,node_viewer,node_player,node_person toneBlue
class node_authroutes,node_middleware,node_models,node_database toneAmber
class node_filesroutes,node_disk,node_service toneMint
class node_adminui,node_storageui,node_adminroutes toneRose
```

## Components

### Web client

- [App routing](https://github.com/aswina1636/home-server/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Auth state](https://github.com/aswina1636/home-server/blob/main/frontend/src/contexts/AuthContext.jsx): `frontend/src/contexts/AuthContext.jsx`
- [API client](https://github.com/aswina1636/home-server/blob/main/frontend/src/api.js): `frontend/src/api.js`
- [File dashboard](https://github.com/aswina1636/home-server/blob/main/frontend/src/pages/Dashboard.jsx): `frontend/src/pages/Dashboard.jsx`
- [File views](https://github.com/aswina1636/home-server/blob/main/frontend/src/components/FileGrid.jsx): `frontend/src/components/FileGrid.jsx`
- [File utilities](https://github.com/aswina1636/home-server/blob/main/frontend/src/utils/fileUtils.js): `frontend/src/utils/fileUtils.js`
- [Media viewer](https://github.com/aswina1636/home-server/blob/main/frontend/src/components/FileViewer.jsx): `frontend/src/components/FileViewer.jsx`
- [Video player](https://github.com/aswina1636/home-server/blob/main/frontend/src/components/VideoPlayer.jsx): `frontend/src/components/VideoPlayer.jsx`

### Identity and security

- [Auth routes](https://github.com/aswina1636/home-server/blob/main/backend/auth.py): `backend/auth.py`
- [Security middleware](https://github.com/aswina1636/home-server/blob/main/backend/middleware.py): `backend/middleware.py`
- [Domain models](https://github.com/aswina1636/home-server/blob/main/backend/models.py): `backend/models.py`
- [SQL database access](https://github.com/aswina1636/home-server/blob/main/backend/database.py): `backend/database.py`

### File and media

- [File routes](https://github.com/aswina1636/home-server/blob/main/backend/files.py): `backend/files.py`
- **File storage**

### Administration

- [Admin pages](https://github.com/aswina1636/home-server/tree/main/frontend/src/pages/admin): `frontend/src/pages/admin`
- [Storage requests](https://github.com/aswina1636/home-server/blob/main/frontend/src/pages/admin/AdminStorageRequests.jsx): `frontend/src/pages/admin/AdminStorageRequests.jsx`
- [Admin routes](https://github.com/aswina1636/home-server/blob/main/backend/admin.py): `backend/admin.py`

### Other components

- **User or admin**
- [FastAPI routes](https://github.com/aswina1636/home-server/blob/main/backend/main.py): `backend/main.py`

## Connections

- User or admin → App routing: uses (evidence: `README.md`)
- App routing → Auth state: provides auth (evidence: `frontend/src/App.jsx`)
- App routing → File dashboard: routes to (evidence: `frontend/src/App.jsx`)
- App routing → Admin pages: routes to (evidence: `frontend/src/App.jsx`)
- Auth state → API client: checks profile (evidence: `frontend/src/contexts/AuthContext.jsx`)
- File dashboard → API client: requests files (evidence: `frontend/src/pages/Dashboard.jsx`)
- File dashboard → File views: renders (evidence: `frontend/src/pages/Dashboard.jsx`)
- File views → File utilities: uses (evidence: `frontend/src/components/FileGrid.jsx`)
- File dashboard → Media viewer: opens files (evidence: `frontend/src/pages/Dashboard.jsx`)
- Media viewer → Video player: embeds (evidence: `frontend/src/components/FileViewer.jsx`)
- Admin pages → API client: requests admin data (evidence: `frontend/src/pages/admin/AdminLayout.jsx`)
- Storage requests → API client: submits decisions (evidence: `frontend/src/pages/admin/AdminStorageRequests.jsx`)
- API client → FastAPI routes: calls HTTP API (evidence: `README.md`)
- FastAPI routes → Auth routes: routes auth (evidence: `backend/main.py`)
- FastAPI routes → File routes: routes files (evidence: `backend/main.py`)
- FastAPI routes → Admin routes: routes admin (evidence: `backend/main.py`)
- FastAPI routes → Security middleware: configures (evidence: `backend/main.py`)
- Auth routes → Domain models: queries users (evidence: `backend/auth.py`)
- Auth routes → SQL database access: gets sessions (evidence: `backend/auth.py`)
- File routes → Domain models: uses records (evidence: `backend/files.py`)
- File routes → SQL database access: gets sessions (evidence: `backend/files.py`)
- File routes → Auth routes: checks identity (evidence: `backend/files.py`)
- File routes → File storage: reads and writes
- Admin routes → Domain models: uses records (evidence: `backend/admin.py`)
- Admin routes → SQL database access: gets sessions (evidence: `backend/admin.py`)
- Admin routes → Auth routes: checks admins (evidence: `backend/admin.py`)
- Domain models → SQL database access: declares tables (evidence: `backend/models.py`)
