# muralimanohar25/mentor-bridge architecture

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

- Interactive diagram: https://gitdiagram.com/muralimanohar25/mentor-bridge
- Repository: https://github.com/muralimanohar25/mentor-bridge

## Overview

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: [`backend/app/api/routes.py`](https://github.com/muralimanohar25/mentor-bridge/blob/main/backend/app/api/routes.py) (API router), [`frontend/src/App.tsx`](https://github.com/muralimanohar25/mentor-bridge/blob/main/frontend/src/App.tsx) (App shell), [`docker-compose.yml`](https://github.com/muralimanohar25/mentor-bridge/blob/main/docker-compose.yml) (Compose), [`backend/app/api`](https://github.com/muralimanohar25/mentor-bridge/tree/main/backend/app/api) (Domain APIs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_browser(("Browser<br/>client runtime"))
  node_frontend_app["App shell<br/>React entry<br/>[App.tsx]"]
  node_frontend_auth["Auth state<br/>react context<br/>[AuthContext.tsx]"]
  node_frontend_features["Dashboards<br/>pages/components"]
  node_frontend_services["API clients<br/>service layer"]
  node_frontend_hooks["UI hooks<br/>state orchestration"]
end

subgraph group_backend["Backend"]
  node_fastapi_main["FastAPI app<br/>backend entrypoint<br/>[main.py]"]
  node_api_router["API router<br/>route aggregator<br/>[routes.py]"]
  node_api_security["Auth API<br/>security boundary<br/>[auth.py]"]
  node_domain_apis["Domain APIs<br/>feature routes"]
  node_core_auth["Core auth<br/>jwt/security<br/>[auth.py]"]
  node_persistence[("DB layer<br/>async sql layer")]
  node_domain_models["Models"]
  node_domain_schemas["Schemas<br/>pydantic dto"]
  node_ws_manager["WebSockets<br/>realtime subsystem<br/>[manager.py]"]
end

subgraph group_infra["Infrastructure"]
  node_migrations["Migrations<br/>schema evolution"]
  node_postgres[("PostgreSQL<br/>database")]
  node_compose["Compose<br/>orchestration<br/>[docker-compose.yml]"]
end

node_browser -->|"uses"| node_frontend_app
node_frontend_app -->|"reads session"| node_frontend_auth
node_frontend_app -->|"renders"| node_frontend_features
node_frontend_features -->|"uses hooks"| node_frontend_hooks
node_frontend_hooks -->|"calls APIs"| node_frontend_services
node_frontend_services -->|"REST"| node_api_router
node_frontend_auth -->|"login/guard"| node_api_security
node_fastapi_main -->|"mounts"| node_api_router
node_api_router -->|"includes"| node_api_security
node_api_router -->|"includes"| node_domain_apis
node_api_security -->|"delegates"| node_core_auth
node_domain_apis -->|"validates"| node_domain_schemas
node_domain_apis -->|"persists"| node_domain_models
node_domain_models -->|"through session"| node_persistence
node_domain_schemas -.->|"maps to"| node_domain_models
node_persistence -->|"stores data"| node_postgres
node_migrations -.->|"evolves schema"| node_postgres
node_api_router -->|"pushes live events"| node_ws_manager
node_ws_manager -->|"WebSocket"| node_frontend_hooks
node_compose -->|"runs"| node_fastapi_main
node_compose -->|"runs"| node_frontend_app
node_compose -->|"runs"| node_postgres

click node_frontend_app "https://github.com/muralimanohar25/mentor-bridge/blob/main/frontend/src/App.tsx"
click node_frontend_auth "https://github.com/muralimanohar25/mentor-bridge/blob/main/frontend/src/context/AuthContext.tsx"
click node_frontend_features "https://github.com/muralimanohar25/mentor-bridge/tree/main/frontend/src/pages"
click node_frontend_services "https://github.com/muralimanohar25/mentor-bridge/tree/main/frontend/src/services"
click node_frontend_hooks "https://github.com/muralimanohar25/mentor-bridge/tree/main/frontend/src/hooks"
click node_fastapi_main "https://github.com/muralimanohar25/mentor-bridge/blob/main/backend/app/main.py"
click node_api_router "https://github.com/muralimanohar25/mentor-bridge/blob/main/backend/app/api/routes.py"
click node_api_security "https://github.com/muralimanohar25/mentor-bridge/blob/main/backend/app/api/auth.py"
click node_domain_apis "https://github.com/muralimanohar25/mentor-bridge/tree/main/backend/app/api"
click node_core_auth "https://github.com/muralimanohar25/mentor-bridge/blob/main/backend/app/core/auth.py"
click node_persistence "https://github.com/muralimanohar25/mentor-bridge/tree/main/backend/app/db"
click node_domain_models "https://github.com/muralimanohar25/mentor-bridge/tree/main/backend/app/models"
click node_domain_schemas "https://github.com/muralimanohar25/mentor-bridge/tree/main/backend/app/schemas"
click node_ws_manager "https://github.com/muralimanohar25/mentor-bridge/blob/main/backend/app/websockets/manager.py"
click node_migrations "https://github.com/muralimanohar25/mentor-bridge/tree/main/backend/alembic"
click node_compose "https://github.com/muralimanohar25/mentor-bridge/blob/main/docker-compose.yml"

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_browser,node_frontend_app,node_frontend_auth,node_frontend_features,node_frontend_services,node_frontend_hooks toneBlue
class node_fastapi_main,node_api_router,node_api_security,node_domain_apis,node_core_auth,node_persistence,node_domain_models,node_domain_schemas,node_ws_manager toneAmber
class node_migrations,node_postgres,node_compose toneMint
```

## Components

### Frontend

React + TypeScript application

- **Browser**: client runtime · Users access the web app here
- [App shell](https://github.com/muralimanohar25/mentor-bridge/blob/main/frontend/src/App.tsx): React entry · Top-level routing and page composition · `frontend/src/App.tsx`
- [Auth state](https://github.com/muralimanohar25/mentor-bridge/blob/main/frontend/src/context/AuthContext.tsx): react context · Session state and protected routing · `frontend/src/context/AuthContext.tsx`
- [Dashboards](https://github.com/muralimanohar25/mentor-bridge/tree/main/frontend/src/pages): pages/components · Role-based pages and reusable UI widgets · `frontend/src/pages`
- [API clients](https://github.com/muralimanohar25/mentor-bridge/tree/main/frontend/src/services): service layer · Typed wrappers for backend domains · `frontend/src/services`
- [UI hooks](https://github.com/muralimanohar25/mentor-bridge/tree/main/frontend/src/hooks): state orchestration · Dashboard loading, notifications, and UI behavior · `frontend/src/hooks`

### Backend

FastAPI service and domain modules

- [FastAPI app](https://github.com/muralimanohar25/mentor-bridge/blob/main/backend/app/main.py): backend entrypoint · ASGI application startup and mounting · `backend/app/main.py`
- [API router](https://github.com/muralimanohar25/mentor-bridge/blob/main/backend/app/api/routes.py): route aggregator · Mounts auth and domain routers · `backend/app/api/routes.py`
- [Auth API](https://github.com/muralimanohar25/mentor-bridge/blob/main/backend/app/api/auth.py): security boundary · Login, JWT, and role-based access control · `backend/app/api/auth.py`
- [Domain APIs](https://github.com/muralimanohar25/mentor-bridge/tree/main/backend/app/api): feature routes · Admin, alumni, jobs, events, announcements, meeting, mentorship handlers · `backend/app/api`
- [Core auth](https://github.com/muralimanohar25/mentor-bridge/blob/main/backend/app/core/auth.py): jwt/security · Shared authentication and authorization helpers · `backend/app/core/auth.py`
- [DB layer](https://github.com/muralimanohar25/mentor-bridge/tree/main/backend/app/db): async sql layer · Session setup, base metadata, and DB initialization · `backend/app/db`
- [Models](https://github.com/muralimanohar25/mentor-bridge/tree/main/backend/app/models): orm models · SQLAlchemy entities for users and platform features · `backend/app/models`
- [Schemas](https://github.com/muralimanohar25/mentor-bridge/tree/main/backend/app/schemas): pydantic dto · Request and response contracts for API boundaries · `backend/app/schemas`
- [WebSockets](https://github.com/muralimanohar25/mentor-bridge/blob/main/backend/app/websockets/manager.py): realtime subsystem · Per-user connection manager for live updates · `backend/app/websockets/manager.py`

### Infrastructure

Database, migrations, and orchestration

- [Migrations](https://github.com/muralimanohar25/mentor-bridge/tree/main/backend/alembic): schema evolution · Alembic versioned database changes · `backend/alembic`
- **PostgreSQL**: database · Primary persistent store
- [Compose](https://github.com/muralimanohar25/mentor-bridge/blob/main/docker-compose.yml): orchestration · Local multi-service runtime for frontend, backend, and database · `docker-compose.yml`

## Connections

- 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
