How arjun-bhattarai/smart-college-hub works
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: submission_repository.py Repositories · docker-compose.yml Docker Compose · resource_service.py Resource service · api.js API client
Components 19
React frontend
- React/Vite SPA
Frontend/src/start.js - TanStack routes and shell · Generated routes cover challenge and collaboration workflows.
Frontend/src/router.jsx - API client
Frontend/src/lib/api.js - Client auth state
Frontend/src/lib/auth-context.jsx
FastAPI API
- FastAPI application
Backend/app/main.py - Versioned REST routes · Auth, challenge, resource, and collaboration endpoints.
- Auth and collaboration access · Protects authenticated and collaboration-scoped operations.
Backend/app/dependencies/auth.py - JWT and role security · Issues and validates tokens and hashes passwords.
Backend/app/core/security.py
Domain and persistence
- Challenge and submission service · Handles submissions, review, personal views, and leaderboards.
Backend/app/services/coding_challenge_service.py - Collaboration service · Manages groups, memberships, and join requests.
Backend/app/services/collaboration_service.py - Resource service
Backend/app/services/resource_service.py - Repositories · Services use repositories for domain data access.
Backend/app/repositories/submission_repository.py - SQLModel domain models · Maps users, challenges, submissions, memberships, and resources.
Backend/app/models/submission.py
Storage and deployment
- Docker Compose · Coordinates the application and data services.
docker-compose.yml - Async database session
Backend/app/db/session.py - PostgreSQL
- Redis
Backend/app/db/redis.py - Resource uploads · Stores uploaded resource files.
- Alembic migrations
Backend/app/alembic/versions/770cd1cdc25b_create_challenge_tables.py
Connections 24
- 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