How muralimanohar25/mentor-bridge works
1. Overall shape
- This is a two-tier alumni management platform: a FastAPI backend exposes REST and WebSocket APIs, and a React + TypeScript frontend consumes those APIs.
- The system is centered on role-based users: admin, alumni, and student. The frontend and backend both branch heavily on those roles.
2. Backend entrypoint and API boundary
- backend/app/main.py is the FastAPI application entrypoint.
- backend/app/api/routes.py appears to be the router aggregator that mounts domain routes such as auth, admin, alumni, jobs, events, announcements, meeting, and mentorship.
- This gives a clean boundary: HTTP requests enter through FastAPI routers, then hit domain-specific handlers.
3. Domain modules
- The backend is split by business domain rather than by technical layer:
- auth for login/token-related concerns
- admin for verification and management workflows
- alumni for alumni profile and management features
- jobs, events, announcements, meeting, mentorship for the core platform features
- The presence of matching models/ and schemas/ files for each domain shows a consistent pattern of persistence model + API DTO separation.
4. Data and persistence layer
- backend/app/models/ contains SQLAlchemy ORM models backed by PostgreSQL.
- backend/app/schemas/ contains Pydantic request/response schemas used at the API boundary.
- backend/app/db/session.py, base.py, and init_db.py define the database session setup and startup initialization path.
- Migrations live under backend/alembic/, which makes schema evolution explicit and versioned.
5. Backend runtime and infrastructure
- The backend uses async FastAPI, SQLAlchemy 2.0 async, and asyncpg against PostgreSQL.
- backend/Dockerfile and docker-compose.yml show it is designed to run as a containerized service alongside the database and frontend.
- backend/.env.example and the README environment variables indicate configuration is externalized via environment variables, especially for DB URL, JWT settings, and CORS.
6. Authentication and authorization
- backend/app/core/auth.py and backend/app/api/auth.py are the key security boundary.
- The README and file tree suggest JWT-based auth is intended, with role-based access control enforced server-side.
- Admin, alumni, and student views are not just UI variants; they map to different backend permissions and workflows.
7. Real-time messaging
- backend/app/websockets/manager.py provides a connection manager for WebSocket clients.
- The README’s /api/ws/{user_id} endpoint implies per-user socket connections and broadcast support for notifications or announcements.
- This is the main non-REST data flow: backend events can be pushed to connected clients without polling.
8. Frontend application structure
- The frontend is a Vite-built React 18 app with TypeScript and Tailwind.
- src/App.tsx is the top-level routing shell.
- src/context/AuthContext.tsx holds shared authentication/session state, while src/components/ProtectedRoute.tsx enforces route access by auth state and likely role.
9. Frontend feature composition
- UI is organized around reusable components and page-level screens:
- pages: landing, home, login, signup, student dashboard, alumni dashboard, admin dashboard
- components: modals, forms, table views, navbar, layout, toast, loading
- This suggests the frontend is not a single SPA view but a set of role-specific dashboard experiences built from shared UI primitives.
10. Frontend-to-backend data flow
- src/services/ contains API client wrappers for each backend domain, so the frontend does not talk to endpoints directly from components.
- src/hooks/ wraps those service calls into stateful UI behavior such as notifications, debouncing, and dashboard data loading.
- This creates a clean separation: components render, hooks orchestrate state, services handle transport.
11. Operational lifecycle
- docker-compose.yml is the main local orchestration point for backend, frontend, and PostgreSQL.
- frontend/Dockerfile, frontend/nginx.conf, and render.yaml indicate the app can also be deployed in a containerized hosting environment, with the frontend likely served through Nginx in production.
- backend/alembic migrations and scripts/supabase_schema.sql show the schema can be initialized or synchronized outside normal app startup.
12. Mental model for an architecture diagram
- Draw three major runtime nodes: browser/frontend, FastAPI backend, and PostgreSQL.
- Show the frontend calling the backend via REST for CRUD and auth flows, and connecting separately over WebSocket for live notifications.
- Inside the backend, show routers feeding into domain models/schemas and then into the async DB layer, with the WebSocket manager as a parallel real-time subsystem.
Main entry points: routes.py API router · App.tsx App shell · docker-compose.yml Compose · api Domain APIs
Components 18
Frontend
React + TypeScript application
- Browser · Users access the web app here
- App shell · Top-level routing and page composition
frontend/src/App.tsx - Auth state · Session state and protected routing
frontend/src/context/AuthContext.tsx - Dashboards · Role-based pages and reusable UI widgets
frontend/src/pages - API clients · Typed wrappers for backend domains
frontend/src/services - UI hooks · Dashboard loading, notifications, and UI behavior
frontend/src/hooks
Backend
FastAPI service and domain modules
- FastAPI app · ASGI application startup and mounting
backend/app/main.py - API router · Mounts auth and domain routers
backend/app/api/routes.py - Auth API · Login, JWT, and role-based access control
backend/app/api/auth.py - Domain APIs · Admin, alumni, jobs, events, announcements, meeting, mentorship handlers
backend/app/api - Core auth · Shared authentication and authorization helpers
backend/app/core/auth.py - DB layer · Session setup, base metadata, and DB initialization
backend/app/db - Models · SQLAlchemy entities for users and platform features
backend/app/models - Schemas · Request and response contracts for API boundaries
backend/app/schemas - WebSockets · Per-user connection manager for live updates
backend/app/websockets/manager.py
Infrastructure
Database, migrations, and orchestration
- Migrations · Alembic versioned database changes
backend/alembic - PostgreSQL · Primary persistent store
- Compose · Local multi-service runtime for frontend, backend, and database
docker-compose.yml
Connections 22
- Browser → App shell: uses · Loads the single-page application
- App shell → Auth state: reads session · Routes and UI depend on auth state
- App shell → Dashboards: renders · Composes role-specific screens and shared components
- Dashboards → UI hooks: uses hooks · Pages rely on stateful behavior and loading logic
- UI hooks → API clients: calls APIs · Hooks orchestrate transport-layer requests
- API clients → API router: REST · HTTP CRUD and auth requests go to the backend
- Auth state → Auth API: login/guard · Session and access control align with server-side auth
- FastAPI app → API router: mounts · Application startup registers the API surface
- API router → Auth API: includes · Authentication routes are part of the router set
- API router → Domain APIs: includes · Domain-specific feature routes are mounted here
- Auth API → Core auth: delegates · JWT and authorization logic is centralized
- Domain APIs → Schemas: validates · Endpoints use DTOs at the HTTP boundary
- Domain APIs → Models: persists · Handlers read and write ORM entities
- Models → DB layer: through session · ORM access goes through the async DB layer
- Schemas → Models: maps to · Request/response shapes mirror persisted data
- DB layer → PostgreSQL: stores data · Async SQLAlchemy talks to PostgreSQL
- Migrations → PostgreSQL: evolves schema · Alembic applies versioned database changes
- API router → WebSockets: pushes live events · Realtime notifications are exposed alongside REST
- WebSockets → UI hooks: WebSocket · Client hooks consume live updates and notifications
- Compose → FastAPI app: runs · Orchestrates backend service startup
- Compose → App shell: runs · Orchestrates frontend service startup
- Compose → PostgreSQL: runs · Provisioned as the persistent database service