# kavalasujathaa-droid/studyhub-v2 architecture

> Architecture diagram of the GitHub repository kavalasujathaa-droid/studyhub-v2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kavalasujathaa-droid/studyhub-v2
- Repository: https://github.com/kavalasujathaa-droid/studyhub-v2

## Overview

StudyHub is a multi-tenant educational PDF library. Administrators curate subjects, titles, and PDFs; students discover and read materials while maintaining personal learning records; a platform owner provisions administrators and oversees platform operations. Flask blueprints handle role-specific requests and delegate domain work to services, with SQL-backed metadata and private object storage. The README documents direct browser-to-R2 uploads and TiDB/R2 deployments. Some service and blueprint relationships below rely on the SOURCE INDEX import references; unsampled internals are not asserted beyond those references.

Main entry points: [`studyhub/services/content_service.py`](https://github.com/kavalasujathaa-droid/studyhub-v2/blob/main/studyhub/services/content_service.py) (Content service), [`studyhub/blueprints/api.py`](https://github.com/kavalasujathaa-droid/studyhub-v2/blob/main/studyhub/blueprints/api.py) (Content API), [`studyhub/services/communication_service.py`](https://github.com/kavalasujathaa-droid/studyhub-v2/blob/main/studyhub/services/communication_service.py) (Communications), [`studyhub/blueprints/owner.py`](https://github.com/kavalasujathaa-droid/studyhub-v2/blob/main/studyhub/blueprints/owner.py) (Owner console)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access and governance"]
  node_webapp["Flask application<br/>[__init__.py]"]
  node_authroutes["Authentication<br/>[auth.py]"]
  node_authservice["Auth service<br/>[auth_service.py]"]
  node_ownerconsole["Owner console<br/>[owner.py]"]
  node_auditservice["Audit service<br/>[audit_service.py]"]
end

subgraph group_library["Library management"]
  node_adminconsole["Admin console<br/>[admin.py]"]
  node_contentapi["Content API<br/>[api.py]"]
  node_contentservice["Content service<br/>[content_service.py]"]
  node_uploadjs["Browser upload<br/>[upload.js]"]
end

subgraph group_learning["Student learning"]
  node_studentportal["Student portal<br/>[student.py]"]
  node_engagement["Engagement service"]
  node_communication["Communications"]
end

subgraph group_data["Data and storage"]
  node_contentmodels["Library records<br/>[content.py]"]
  node_metadata["Categories and tags<br/>[metadata.py]"]
  node_users["User records<br/>[user.py]"]
  node_personaldata["Learning records<br/>[personalization.py]"]
  node_commmodels["Communication records<br/>[communication.py]"]
  node_auditmodels["Audit records<br/>[audit.py]"]
  node_storage["Object storage service<br/>[storage_service.py]"]
  node_extensions["Persistence extensions<br/>[extensions.py]"]
  node_database[("TiDB database")]
  node_r2[("Cloudflare R2")]
end

node_owner(("Platform owner"))
node_administrator(("Administrator"))
node_student(("Student"))

node_owner -->|"manages"| node_ownerconsole
node_administrator -->|"curates"| node_adminconsole
node_student -->|"uses"| node_studentportal
node_webapp -->|"registers"| node_authroutes
node_webapp -->|"registers"| node_ownerconsole
node_webapp -->|"registers"| node_adminconsole
node_webapp -->|"registers"| node_studentportal
node_webapp -->|"registers"| node_contentapi
node_authroutes -->|"bootstraps"| node_authservice
node_authroutes -->|"queries"| node_users
node_authservice -->|"authenticates"| node_users
node_authservice -->|"records"| node_auditmodels
node_ownerconsole -->|"uses"| node_authservice
node_ownerconsole -->|"uses"| node_contentservice
node_ownerconsole -->|"uses"| node_communication
node_ownerconsole -->|"uses"| node_auditservice
node_adminconsole -->|"delegates"| node_contentservice
node_adminconsole -->|"uses"| node_communication
node_contentapi -->|"delegates"| node_contentservice
node_contentapi -->|"requests URLs"| node_storage
node_contentapi -->|"records activity"| node_engagement
node_contentapi -->|"uses"| node_communication
node_contentapi -->|"uses"| node_auditservice
node_studentportal -->|"loads library"| node_contentservice
node_studentportal -->|"records activity"| node_engagement
node_studentportal -->|"requests access"| node_storage
node_studentportal -->|"uses"| node_communication
node_contentservice -->|"manages"| node_contentmodels
node_contentservice -->|"uses"| node_metadata
node_contentservice -->|"verifies uploads"| node_storage
node_engagement -->|"stores"| node_personaldata
node_engagement -->|"reads"| node_contentmodels
node_communication -->|"manages"| node_commmodels
node_communication -->|"checks PDFs"| node_contentmodels
node_communication -->|"targets users"| node_users
node_auditservice -->|"writes"| node_auditmodels
node_storage -->|"checks duplicates"| node_contentmodels
node_extensions -.->|"connects ORM"| node_database
node_contentservice -.->|"persists library"| node_database
node_engagement -.->|"persists activity"| node_database
node_storage -->|"presigns and inspects"| node_r2
node_uploadjs -.->|"requests upload URL"| node_contentapi
node_uploadjs -->|"uploads directly"| node_r2

click node_webapp "https://github.com/kavalasujathaa-droid/studyhub-v2/blob/main/studyhub/__init__.py"
click node_authroutes "https://github.com/kavalasujathaa-droid/studyhub-v2/blob/main/studyhub/blueprints/auth.py"
click node_authservice "https://github.com/kavalasujathaa-droid/studyhub-v2/blob/main/studyhub/services/auth_service.py"
click node_ownerconsole "https://github.com/kavalasujathaa-droid/studyhub-v2/blob/main/studyhub/blueprints/owner.py"
click node_adminconsole "https://github.com/kavalasujathaa-droid/studyhub-v2/blob/main/studyhub/blueprints/admin.py"
click node_contentapi "https://github.com/kavalasujathaa-droid/studyhub-v2/blob/main/studyhub/blueprints/api.py"
click node_contentservice "https://github.com/kavalasujathaa-droid/studyhub-v2/blob/main/studyhub/services/content_service.py"
click node_studentportal "https://github.com/kavalasujathaa-droid/studyhub-v2/blob/main/studyhub/blueprints/student.py"
click node_engagement "https://github.com/kavalasujathaa-droid/studyhub-v2/blob/main/studyhub/services/engagement_service.py"
click node_communication "https://github.com/kavalasujathaa-droid/studyhub-v2/blob/main/studyhub/services/communication_service.py"
click node_auditservice "https://github.com/kavalasujathaa-droid/studyhub-v2/blob/main/studyhub/services/audit_service.py"
click node_contentmodels "https://github.com/kavalasujathaa-droid/studyhub-v2/blob/main/studyhub/models/content.py"
click node_metadata "https://github.com/kavalasujathaa-droid/studyhub-v2/blob/main/studyhub/models/metadata.py"
click node_users "https://github.com/kavalasujathaa-droid/studyhub-v2/blob/main/studyhub/models/user.py"
click node_personaldata "https://github.com/kavalasujathaa-droid/studyhub-v2/blob/main/studyhub/models/personalization.py"
click node_commmodels "https://github.com/kavalasujathaa-droid/studyhub-v2/blob/main/studyhub/models/communication.py"
click node_auditmodels "https://github.com/kavalasujathaa-droid/studyhub-v2/blob/main/studyhub/models/audit.py"
click node_storage "https://github.com/kavalasujathaa-droid/studyhub-v2/blob/main/studyhub/services/storage_service.py"
click node_extensions "https://github.com/kavalasujathaa-droid/studyhub-v2/blob/main/studyhub/extensions.py"
click node_uploadjs "https://github.com/kavalasujathaa-droid/studyhub-v2/blob/main/studyhub/static/js/upload.js"

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_webapp,node_authroutes,node_authservice,node_ownerconsole,node_auditservice toneBlue
class node_adminconsole,node_contentapi,node_contentservice,node_uploadjs toneAmber
class node_studentportal,node_engagement,node_communication toneMint
class node_contentmodels,node_metadata,node_users,node_personaldata,node_commmodels,node_auditmodels,node_storage,node_extensions,node_database,node_r2 toneRose
class node_owner,node_administrator,node_student toneIndigo
```

## Components

### Access and governance

- [Flask application](https://github.com/kavalasujathaa-droid/studyhub-v2/blob/main/studyhub/__init__.py): `studyhub/__init__.py`
- [Authentication](https://github.com/kavalasujathaa-droid/studyhub-v2/blob/main/studyhub/blueprints/auth.py): `studyhub/blueprints/auth.py`
- [Auth service](https://github.com/kavalasujathaa-droid/studyhub-v2/blob/main/studyhub/services/auth_service.py): `studyhub/services/auth_service.py`
- [Owner console](https://github.com/kavalasujathaa-droid/studyhub-v2/blob/main/studyhub/blueprints/owner.py): `studyhub/blueprints/owner.py`
- [Audit service](https://github.com/kavalasujathaa-droid/studyhub-v2/blob/main/studyhub/services/audit_service.py): `studyhub/services/audit_service.py`

### Library management

- [Admin console](https://github.com/kavalasujathaa-droid/studyhub-v2/blob/main/studyhub/blueprints/admin.py): `studyhub/blueprints/admin.py`
- [Content API](https://github.com/kavalasujathaa-droid/studyhub-v2/blob/main/studyhub/blueprints/api.py): `studyhub/blueprints/api.py`
- [Content service](https://github.com/kavalasujathaa-droid/studyhub-v2/blob/main/studyhub/services/content_service.py): `studyhub/services/content_service.py`
- [Browser upload](https://github.com/kavalasujathaa-droid/studyhub-v2/blob/main/studyhub/static/js/upload.js): `studyhub/static/js/upload.js`

### Student learning

- [Student portal](https://github.com/kavalasujathaa-droid/studyhub-v2/blob/main/studyhub/blueprints/student.py): `studyhub/blueprints/student.py`
- [Engagement service](https://github.com/kavalasujathaa-droid/studyhub-v2/blob/main/studyhub/services/engagement_service.py): `studyhub/services/engagement_service.py`
- [Communications](https://github.com/kavalasujathaa-droid/studyhub-v2/blob/main/studyhub/services/communication_service.py): `studyhub/services/communication_service.py`

### Data and storage

- [Library records](https://github.com/kavalasujathaa-droid/studyhub-v2/blob/main/studyhub/models/content.py): `studyhub/models/content.py`
- [Categories and tags](https://github.com/kavalasujathaa-droid/studyhub-v2/blob/main/studyhub/models/metadata.py): `studyhub/models/metadata.py`
- [User records](https://github.com/kavalasujathaa-droid/studyhub-v2/blob/main/studyhub/models/user.py): `studyhub/models/user.py`
- [Learning records](https://github.com/kavalasujathaa-droid/studyhub-v2/blob/main/studyhub/models/personalization.py): `studyhub/models/personalization.py`
- [Communication records](https://github.com/kavalasujathaa-droid/studyhub-v2/blob/main/studyhub/models/communication.py): `studyhub/models/communication.py`
- [Audit records](https://github.com/kavalasujathaa-droid/studyhub-v2/blob/main/studyhub/models/audit.py): `studyhub/models/audit.py`
- [Object storage service](https://github.com/kavalasujathaa-droid/studyhub-v2/blob/main/studyhub/services/storage_service.py): `studyhub/services/storage_service.py`
- [Persistence extensions](https://github.com/kavalasujathaa-droid/studyhub-v2/blob/main/studyhub/extensions.py): `studyhub/extensions.py`
- **TiDB database**
- **Cloudflare R2**

### Other components

- **Platform owner**
- **Administrator**
- **Student**

## Connections

- Platform owner → Owner console: manages (evidence: `README.md`)
- Administrator → Admin console: curates (evidence: `README.md`)
- Student → Student portal: uses (evidence: `README.md`)
- Flask application → Authentication: registers (evidence: `studyhub/__init__.py`)
- Flask application → Owner console: registers (evidence: `studyhub/__init__.py`)
- Flask application → Admin console: registers (evidence: `studyhub/__init__.py`)
- Flask application → Student portal: registers (evidence: `studyhub/__init__.py`)
- Flask application → Content API: registers (evidence: `studyhub/__init__.py`)
- Authentication → Auth service: bootstraps (evidence: `studyhub/blueprints/auth.py`)
- Authentication → User records: queries (evidence: `studyhub/blueprints/auth.py`)
- Auth service → User records: authenticates (evidence: `studyhub/services/auth_service.py`)
- Auth service → Audit records: records (evidence: `studyhub/services/auth_service.py`)
- Owner console → Auth service: uses (evidence: `studyhub/blueprints/owner.py`)
- Owner console → Content service: uses (evidence: `studyhub/blueprints/owner.py`)
- Owner console → Communications: uses (evidence: `studyhub/blueprints/owner.py`)
- Owner console → Audit service: uses (evidence: `studyhub/blueprints/owner.py`)
- Admin console → Content service: delegates (evidence: `studyhub/blueprints/admin.py`)
- Admin console → Communications: uses (evidence: `studyhub/blueprints/admin.py`)
- Content API → Content service: delegates (evidence: `studyhub/blueprints/api.py`)
- Content API → Object storage service: requests URLs (evidence: `studyhub/blueprints/api.py`)
- Content API → Engagement service: records activity (evidence: `studyhub/blueprints/api.py`)
- Content API → Communications: uses (evidence: `studyhub/blueprints/api.py`)
- Content API → Audit service: uses (evidence: `studyhub/blueprints/api.py`)
- Student portal → Content service: loads library (evidence: `studyhub/blueprints/student.py`)
- Student portal → Engagement service: records activity (evidence: `studyhub/blueprints/student.py`)
- Student portal → Object storage service: requests access (evidence: `studyhub/blueprints/student.py`)
- Student portal → Communications: uses (evidence: `studyhub/blueprints/student.py`)
- Content service → Library records: manages (evidence: `studyhub/services/content_service.py`)
- Content service → Categories and tags: uses (evidence: `studyhub/services/content_service.py`)
- Content service → Object storage service: verifies uploads (evidence: `studyhub/services/content_service.py`)
- Engagement service → Learning records: stores (evidence: `studyhub/services/engagement_service.py`)
- Engagement service → Library records: reads (evidence: `studyhub/services/engagement_service.py`)
- Communications → Communication records: manages (evidence: `studyhub/services/communication_service.py`)
- Communications → Library records: checks PDFs (evidence: `studyhub/services/communication_service.py`)
- Communications → User records: targets users (evidence: `studyhub/services/communication_service.py`)
- Audit service → Audit records: writes (evidence: `studyhub/services/audit_service.py`)
- Object storage service → Library records: checks duplicates (evidence: `studyhub/services/storage_service.py`)
- Persistence extensions → TiDB database: connects ORM (evidence: `README.md`)
- Content service → TiDB database: persists library
- Engagement service → TiDB database: persists activity
- Object storage service → Cloudflare R2: presigns and inspects (evidence: `README.md`)
- Browser upload → Content API: requests upload URL (evidence: `README.md`)
- Browser upload → Cloudflare R2: uploads directly (evidence: `README.md`)