# arjun-bhattarai/smart-college-hub architecture

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

- Interactive diagram: https://gitdiagram.com/arjun-bhattarai/smart-college-hub
- Repository: https://github.com/arjun-bhattarai/smart-college-hub

## Overview

#### Purpose and deployment
Smart College Hub is a containerized college collaboration platform for authenticated users, coding challenges/submissions/leaderboards, and collaboration groups. Docker Compose coordinates React frontend, FastAPI backend, PostgreSQL, and Redis: `docker-compose.yml`, `Backend/Dockerfile`, `Frontend/Dockerfile`.

#### Application entry points
The backend FastAPI application starts at `Backend/app/main.py`, with versioned REST handlers under `Backend/app/api/v1/`. The frontend starts through `Frontend/src/start.js` / `Frontend/src/server.js`; routing is configured in `Frontend/src/router.jsx` and generated from route files.

#### Frontend application boundary
The React/Vite SPA is organized around TanStack Router screens and a shared shell. Route modules represent user, admin, challenge, collaboration, resource, and account workflows: `Frontend/src/routes/__root.jsx`, `Frontend/src/routes/challenges.$challengeId.jsx`, `Frontend/src/routes/collaborations.$collaborationId.index.jsx`. `Frontend/src/lib/api.js` centralizes calls across the HTTP boundary, while `Frontend/src/lib/auth-context.jsx` holds client authentication state.

#### API and authorization layer
FastAPI route modules expose auth/token, coding challenge, resource, and collaboration operations: `Backend/app/api/v1/auth.py`, `Backend/app/api/v1/coding_challenge.py`, `Backend/app/api/v1/collaboration/collaboration.py`. Dependencies enforce authentication and collaboration-scoped access: `Backend/app/dependencies/auth.py`, `Backend/app/dependencies/collaboration.py`. JWT issuance/validation, password hashing, and role-based protection are centralized in `Backend/app/core/security.py` and `Backend/app/services/auth_service.py`.

#### Domain service and persistence layers
Route handlers delegate business rules to services, which use repositories as the database boundary. Core domains are coding challenges/submissions, collaborations, memberships/join requests, and resources: `Backend/app/services/coding_challenge_service.py`, `Backend/app/services/collaboration_service.py`, `Backend/app/services/resource_service.py`; `Backend/app/repositories/submission_repository.py`, `Backend/app/repositories/collaboration_membership_repository.py`. Request/response contracts live in schemas and persistence mappings in models, e.g. `Backend/app/schemas/submission_schema.py`, `Backend/app/models/coding_challenge.py`, `Backend/app/models/user.py`.

#### Primary flows
Authentication flows from frontend API client to auth/token routes, then security/auth services; user identity and roles control protected routes. Challenge flows list/detail challenges, create submissions, permit admin review/deletion, and derive personal-submission and leaderboard views. Collaboration flows create/update/delete groups, then process join requests and membership changes through separate API/service/repository paths: `Backend/app/api/v1/collaboration/join_request.py`, `Backend/app/services/collaboration_join_request_service.py`, `Backend/app/models/collaboration_membership.py`.

#### State, storage, and schema evolution
PostgreSQL is accessed asynchronously through the session layer, with SQLModel/SQLAlchemy models and Alembic migrations: `Backend/app/db/session.py`, `Backend/app/models/submission.py`, `Backend/app/alembic/versions/770cd1cdc25b_create_challenge_tables.py`. Redis is a separate infrastructure boundary used for token blacklisting and caching: `Backend/app/db/redis.py`. Resource uploads are filesystem-backed under `Backend/uploads/resources/`, with resource and request records modeled separately: `Backend/app/models/resource.py`, `Backend/app/models/resource_request.py`.

Main entry points: [`Backend/app/repositories/submission_repository.py`](https://github.com/arjun-bhattarai/smart-college-hub/blob/main/Backend/app/repositories/submission_repository.py) (Repositories), [`docker-compose.yml`](https://github.com/arjun-bhattarai/smart-college-hub/blob/main/docker-compose.yml) (Docker Compose), [`Backend/app/services/resource_service.py`](https://github.com/arjun-bhattarai/smart-college-hub/blob/main/Backend/app/services/resource_service.py) (Resource service), [`Frontend/src/lib/api.js`](https://github.com/arjun-bhattarai/smart-college-hub/blob/main/Frontend/src/lib/api.js) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React frontend"]
  node_frontend["React/Vite SPA<br/>frontend runtime<br/>[start.js]"]
  node_router["TanStack routes and shell<br/>routing<br/>[router.jsx]"]
  node_api_client["API client<br/>HTTP client<br/>[api.js]"]
  node_auth_context["Client auth state<br/>[auth-context.jsx]"]
end

subgraph group_api["FastAPI API"]
  node_backend["FastAPI application<br/>backend runtime<br/>[main.py]"]
  node_api_routes["Versioned REST routes<br/>route handlers"]
  node_access_control["Auth and collaboration access<br/>dependencies<br/>[auth.py]"]
  node_security["JWT and role security<br/>security service<br/>[security.py]"]
end

subgraph group_domain["Domain and persistence"]
  node_challenge_service["Challenge and submission service<br/>domain service"]
  node_collaboration_service["Collaboration service<br/>domain service"]
  node_resource_service["Resource service<br/>domain service"]
  node_repositories["Repositories<br/>persistence boundary"]
  node_models["SQLModel domain models<br/>ORM models<br/>[submission.py]"]
end

subgraph group_infra["Storage and deployment"]
  node_compose{{"Docker Compose<br/>deployment<br/>[docker-compose.yml]"}}
  node_db_session["Async database session<br/>database access<br/>[session.py]"]
  node_postgres[("PostgreSQL<br/>relational database")]
  node_redis[("Redis<br/>cache and token blacklist<br/>[redis.py]")]
  node_uploads["Resource uploads<br/>filesystem storage"]
  node_migrations["Alembic migrations<br/>schema evolution"]
end

node_compose -->|"runs"| node_frontend
node_compose -->|"runs"| node_backend
node_compose -->|"provisions"| node_postgres
node_compose -->|"provisions"| node_redis
node_frontend -->|"renders"| node_router
node_router -->|"screens call"| node_api_client
node_auth_context -->|"supplies identity"| node_api_client
node_api_client -->|"HTTPS REST"| node_api_routes
node_backend -->|"mounts"| node_api_routes
node_api_routes -->|"enforces"| node_access_control
node_access_control -->|"validates JWTs"| node_security
node_api_routes -->|"auth/token flow"| node_security
node_api_routes -->|"challenge operations"| node_challenge_service
node_api_routes -->|"group and join flows"| node_collaboration_service
node_api_routes -->|"resource operations"| node_resource_service
node_challenge_service -->|"persists submissions"| node_repositories
node_collaboration_service -->|"persists memberships"| node_repositories
node_resource_service -->|"persists records"| node_repositories
node_repositories -->|"uses mappings"| node_models
node_repositories -->|"queries through"| node_db_session
node_db_session -->|"async SQL"| node_postgres
node_security -->|"blacklists tokens"| node_redis
node_resource_service -->|"stores files"| node_uploads
node_migrations -->|"evolves schema"| node_postgres

click node_compose "https://github.com/arjun-bhattarai/smart-college-hub/blob/main/docker-compose.yml"
click node_frontend "https://github.com/arjun-bhattarai/smart-college-hub/blob/main/Frontend/src/start.js"
click node_router "https://github.com/arjun-bhattarai/smart-college-hub/blob/main/Frontend/src/router.jsx"
click node_api_client "https://github.com/arjun-bhattarai/smart-college-hub/blob/main/Frontend/src/lib/api.js"
click node_auth_context "https://github.com/arjun-bhattarai/smart-college-hub/blob/main/Frontend/src/lib/auth-context.jsx"
click node_backend "https://github.com/arjun-bhattarai/smart-college-hub/blob/main/Backend/app/main.py"
click node_access_control "https://github.com/arjun-bhattarai/smart-college-hub/blob/main/Backend/app/dependencies/auth.py"
click node_security "https://github.com/arjun-bhattarai/smart-college-hub/blob/main/Backend/app/core/security.py"
click node_challenge_service "https://github.com/arjun-bhattarai/smart-college-hub/blob/main/Backend/app/services/coding_challenge_service.py"
click node_collaboration_service "https://github.com/arjun-bhattarai/smart-college-hub/blob/main/Backend/app/services/collaboration_service.py"
click node_resource_service "https://github.com/arjun-bhattarai/smart-college-hub/blob/main/Backend/app/services/resource_service.py"
click node_repositories "https://github.com/arjun-bhattarai/smart-college-hub/blob/main/Backend/app/repositories/submission_repository.py"
click node_models "https://github.com/arjun-bhattarai/smart-college-hub/blob/main/Backend/app/models/submission.py"
click node_db_session "https://github.com/arjun-bhattarai/smart-college-hub/blob/main/Backend/app/db/session.py"
click node_redis "https://github.com/arjun-bhattarai/smart-college-hub/blob/main/Backend/app/db/redis.py"
click node_migrations "https://github.com/arjun-bhattarai/smart-college-hub/blob/main/Backend/app/alembic/versions/770cd1cdc25b_create_challenge_tables.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_frontend,node_router,node_api_client,node_auth_context toneBlue
class node_backend,node_api_routes,node_access_control,node_security toneAmber
class node_challenge_service,node_collaboration_service,node_resource_service,node_repositories,node_models toneMint
class node_compose,node_db_session,node_postgres,node_redis,node_uploads,node_migrations toneRose
```

## Components

### React frontend

- [React/Vite SPA](https://github.com/arjun-bhattarai/smart-college-hub/blob/main/Frontend/src/start.js): frontend runtime · `Frontend/src/start.js`
- [TanStack routes and shell](https://github.com/arjun-bhattarai/smart-college-hub/blob/main/Frontend/src/router.jsx): routing · Generated routes cover challenge and collaboration workflows. · `Frontend/src/router.jsx`
- [API client](https://github.com/arjun-bhattarai/smart-college-hub/blob/main/Frontend/src/lib/api.js): HTTP client · `Frontend/src/lib/api.js`
- [Client auth state](https://github.com/arjun-bhattarai/smart-college-hub/blob/main/Frontend/src/lib/auth-context.jsx): auth state · `Frontend/src/lib/auth-context.jsx`

### FastAPI API

- [FastAPI application](https://github.com/arjun-bhattarai/smart-college-hub/blob/main/Backend/app/main.py): backend runtime · `Backend/app/main.py`
- **Versioned REST routes**: route handlers · Auth, challenge, resource, and collaboration endpoints.
- [Auth and collaboration access](https://github.com/arjun-bhattarai/smart-college-hub/blob/main/Backend/app/dependencies/auth.py): dependencies · Protects authenticated and collaboration-scoped operations. · `Backend/app/dependencies/auth.py`
- [JWT and role security](https://github.com/arjun-bhattarai/smart-college-hub/blob/main/Backend/app/core/security.py): security service · Issues and validates tokens and hashes passwords. · `Backend/app/core/security.py`

### Domain and persistence

- [Challenge and submission service](https://github.com/arjun-bhattarai/smart-college-hub/blob/main/Backend/app/services/coding_challenge_service.py): domain service · Handles submissions, review, personal views, and leaderboards. · `Backend/app/services/coding_challenge_service.py`
- [Collaboration service](https://github.com/arjun-bhattarai/smart-college-hub/blob/main/Backend/app/services/collaboration_service.py): domain service · Manages groups, memberships, and join requests. · `Backend/app/services/collaboration_service.py`
- [Resource service](https://github.com/arjun-bhattarai/smart-college-hub/blob/main/Backend/app/services/resource_service.py): domain service · `Backend/app/services/resource_service.py`
- [Repositories](https://github.com/arjun-bhattarai/smart-college-hub/blob/main/Backend/app/repositories/submission_repository.py): persistence boundary · Services use repositories for domain data access. · `Backend/app/repositories/submission_repository.py`
- [SQLModel domain models](https://github.com/arjun-bhattarai/smart-college-hub/blob/main/Backend/app/models/submission.py): ORM models · Maps users, challenges, submissions, memberships, and resources. · `Backend/app/models/submission.py`

### Storage and deployment

- [Docker Compose](https://github.com/arjun-bhattarai/smart-college-hub/blob/main/docker-compose.yml): deployment · Coordinates the application and data services. · `docker-compose.yml`
- [Async database session](https://github.com/arjun-bhattarai/smart-college-hub/blob/main/Backend/app/db/session.py): database access · `Backend/app/db/session.py`
- **PostgreSQL**: relational database
- [Redis](https://github.com/arjun-bhattarai/smart-college-hub/blob/main/Backend/app/db/redis.py): cache and token blacklist · `Backend/app/db/redis.py`
- **Resource uploads**: filesystem storage · Stores uploaded resource files.
- [Alembic migrations](https://github.com/arjun-bhattarai/smart-college-hub/blob/main/Backend/app/alembic/versions/770cd1cdc25b_create_challenge_tables.py): schema evolution · `Backend/app/alembic/versions/770cd1cdc25b_create_challenge_tables.py`

## Connections

- Docker Compose → React/Vite SPA: runs
- Docker Compose → FastAPI application: runs
- Docker Compose → PostgreSQL: provisions
- Docker Compose → Redis: provisions
- React/Vite SPA → TanStack routes and shell: renders
- TanStack routes and shell → API client: screens call
- Client auth state → API client: supplies identity
- API client → Versioned REST routes: HTTPS REST
- FastAPI application → Versioned REST routes: mounts
- Versioned REST routes → Auth and collaboration access: enforces
- Auth and collaboration access → JWT and role security: validates JWTs
- Versioned REST routes → JWT and role security: auth/token flow
- Versioned REST routes → Challenge and submission service: challenge operations
- Versioned REST routes → Collaboration service: group and join flows
- Versioned REST routes → Resource service: resource operations
- Challenge and submission service → Repositories: persists submissions
- Collaboration service → Repositories: persists memberships
- Resource service → Repositories: persists records
- Repositories → SQLModel domain models: uses mappings
- Repositories → Async database session: queries through
- Async database session → PostgreSQL: async SQL
- JWT and role security → Redis: blacklists tokens
- Resource service → Resource uploads: stores files
- Alembic migrations → PostgreSQL: evolves schema
