# iftekhartamim595/gradbridge architecture

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

- Interactive diagram: https://gitdiagram.com/iftekhartamim595/gradbridge
- Repository: https://github.com/iftekhartamim595/gradbridge

## Overview

1. GradBridge is a two-tier monolith: a Django backend API and a React/Vite frontend SPA. The backend is split into feature apps rather than microservices, and the frontend consumes those APIs plus a WebSocket chat channel.

2. The backend’s architectural root is `backend/config`, which wires Django settings, ASGI/WGI entrypoints, URL routing, static file serving, JWT auth, CORS, Channels, and production deployment behavior. `Procfile`, `render.yaml`, `runtime.txt`, and `build.sh` show it is intended for hosted deployment with Gunicorn and a managed runtime.

3. Identity and access control are concentrated in `accounts`. This app owns the custom user model, role/approval workflow, Google OAuth integration, serializers/views for auth endpoints, and permission logic. It is the foundation for role-based branching across the rest of the platform.

4. User-facing profile data lives in `profiles`, which models student and alumni profiles, certificates, visibility controls, and profile enrichment. Signals in this app indicate that profile creation/update side effects are automatic rather than manually triggered from the UI.

5. Discovery and matching are handled by `search`, `projects`, and `community`. `search` provides filtered alumni discovery, `projects` stores portfolio/work samples, and `community` appears to support broader social or feed-style interactions. These features depend heavily on profile visibility and user role.

6. Mentorship and job workflows are separate bounded areas. `mentorship` models mentorship requests and their lifecycle, while `jobs` owns job postings, recruiter-specific fields, applications, and related utilities. The README’s recruiter approval flow suggests `accounts` and `jobs` cooperate to enforce who can publish jobs.

7. Real-time communication is implemented with Django Channels in `chat`. The presence of `consumers.py`, `middleware.py`, and `routing.py` indicates WebSocket-based messaging, while REST endpoints still exist for conversation and message history. The frontend has a chat context and socket hook, so chat uses both HTTP for persistence and WebSockets for live delivery.

8. Notifications are a separate event-driven concern in `notifications`. The `signals.py` file suggests notifications are produced by model events across other apps, not only by explicit API calls. This makes notifications a cross-cutting subsystem rather than a standalone user action flow.

9. AI-powered resume analysis is isolated in `ai_insights`, with an `openrouter.py` integration and utilities for processing resume content. The frontend’s `AIInsights` and `ResumeAnalysis` pages likely upload a resume to this API, which then returns scoring, skill-gap analysis, and recommendations. `ml_engine` looks like a separate internal service layer for ML-related logic, but the primary external LLM integration is OpenRouter.

10. Email delivery and validation are centralized under `utils`, especially `email_service.py` and `validators.py`. This keeps outbound communication and shared input checks out of individual feature apps, which is important because chat, mentorship, account actions, and notifications all appear to trigger email side effects.

11. The frontend is a role-aware SPA organized around pages, reusable components, and React contexts. `AuthContext`, `ChatContext`, and `ModalContext` provide shared client-side state, while route guards like `PrivateRoute` and `ApprovedRecruiterRoute` enforce access rules before a screen is rendered.

12. API access on the frontend is centralized in `src/api`, with `apiClient.js` and `ai.js` acting as the main service layer. This means pages do not talk directly to the backend; they go through a common request layer that likely handles JWT attachment, error handling, and environment-based base URLs.

13. The user journeys are clearly role segmented in the page structure: student dashboards and profile views, alumni dashboards and search, recruiter hiring flows, admin pages, messages, community, jobs, mentorship, and resume analysis. That separation mirrors the backend app boundaries, which makes the diagram easier to draw as matching frontend modules to backend domains.

14. Overall data flow is: browser auths against `accounts`, receives JWTs, then uses REST APIs for profiles/search/jobs/mentorship/notifications/AI and WebSockets for chat. Cross-cutting events like profile updates, mentorship actions, and job/application changes can emit notifications and emails, while AI resume uploads go out to OpenRouter through the backend.

Main entry points: [`frontend/src/api`](https://github.com/iftekhartamim595/gradbridge/tree/main/frontend/src/api) (API layer), [`backend/profiles`](https://github.com/iftekhartamim595/gradbridge/tree/main/backend/profiles) (Profiles), [`backend/notifications`](https://github.com/iftekhartamim595/gradbridge/tree/main/backend/notifications) (Notifications), [`backend/accounts`](https://github.com/iftekhartamim595/gradbridge/tree/main/backend/accounts) (Accounts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_backend_config["Core config<br/>django wiring"]
  node_backend_accounts["Accounts<br/>identity"]
  node_backend_profiles["Profiles<br/>profile domain"]
  node_backend_search["Search<br/>discovery"]
  node_backend_projects["Projects<br/>portfolio domain"]
  node_backend_community["Community<br/>social feed"]
  node_backend_jobs["Jobs<br/>hiring domain"]
  node_backend_mentorship["Mentorship<br/>workflow"]
  node_backend_chat["Chat<br/>realtime messaging"]
  node_backend_notifications["Notifications"]
  node_backend_ai["AI insights<br/>llm analysis"]
  node_backend_utils["Shared utils<br/>cross-cutting helpers"]
end

subgraph group_frontend["Frontend"]
  node_frontend_app["SPA shell<br/>react app<br/>[App.jsx]"]
  node_frontend_api["API layer<br/>client services"]
  node_frontend_state(("Client state<br/>react contexts"))
  node_frontend_routes["Route guards<br/>access control"]
  node_frontend_chat["Chat UI<br/>messaging UI"]
  node_frontend_pages["Role pages<br/>screen modules"]
  node_frontend_ai["AI pages<br/>analysis UI<br/>[AIInsights.jsx]"]
end

node_backend_config -->|"auth wiring"| node_backend_accounts
node_backend_config -->|"channels"| node_backend_chat
node_backend_config -.->|"events"| node_backend_notifications
node_backend_accounts -->|"role base"| node_backend_profiles
node_backend_profiles -->|"visibility"| node_backend_search
node_backend_profiles -->|"showcase data"| node_backend_projects
node_backend_accounts -->|"recruiter gate"| node_backend_jobs
node_backend_accounts -->|"access rules"| node_backend_mentorship
node_backend_profiles -.->|"identity data"| node_backend_community
node_backend_chat -.->|"activity alerts"| node_backend_notifications
node_backend_profiles -.->|"signals"| node_backend_notifications
node_backend_jobs -.->|"applications"| node_backend_notifications
node_backend_mentorship -.->|"request events"| node_backend_notifications
node_backend_ai -.->|"validation"| node_backend_utils
node_frontend_app -->|"renders"| node_frontend_routes
node_frontend_app -->|"shared state"| node_frontend_state
node_frontend_app -->|"data access"| node_frontend_api
node_frontend_state -->|"socket state"| node_frontend_chat
node_frontend_api -->|"auth API"| node_backend_accounts
node_frontend_api -->|"profile API"| node_backend_profiles
node_frontend_api -->|"discovery API"| node_backend_search
node_frontend_api -->|"jobs API"| node_backend_jobs
node_frontend_api -->|"mentorship API"| node_backend_mentorship
node_frontend_api -->|"community API"| node_backend_community
node_frontend_api -->|"notifications API"| node_backend_notifications
node_frontend_api -->|"analysis API"| node_backend_ai
node_frontend_chat -->|"websocket"| node_backend_chat
node_frontend_pages -.->|"uses"| node_frontend_api
node_frontend_pages -.->|"messages"| node_frontend_chat
node_frontend_ai -->|"resume analysis"| node_backend_ai

click node_backend_config "https://github.com/iftekhartamim595/gradbridge/tree/main/backend/config"
click node_backend_accounts "https://github.com/iftekhartamim595/gradbridge/tree/main/backend/accounts"
click node_backend_profiles "https://github.com/iftekhartamim595/gradbridge/tree/main/backend/profiles"
click node_backend_search "https://github.com/iftekhartamim595/gradbridge/tree/main/backend/search"
click node_backend_projects "https://github.com/iftekhartamim595/gradbridge/tree/main/backend/projects"
click node_backend_community "https://github.com/iftekhartamim595/gradbridge/tree/main/backend/community"
click node_backend_jobs "https://github.com/iftekhartamim595/gradbridge/tree/main/backend/jobs"
click node_backend_mentorship "https://github.com/iftekhartamim595/gradbridge/tree/main/backend/mentorship"
click node_backend_chat "https://github.com/iftekhartamim595/gradbridge/tree/main/backend/chat"
click node_backend_notifications "https://github.com/iftekhartamim595/gradbridge/tree/main/backend/notifications"
click node_backend_ai "https://github.com/iftekhartamim595/gradbridge/tree/main/backend/ai_insights"
click node_backend_utils "https://github.com/iftekhartamim595/gradbridge/tree/main/backend/utils"
click node_frontend_app "https://github.com/iftekhartamim595/gradbridge/blob/main/frontend/src/App.jsx"
click node_frontend_api "https://github.com/iftekhartamim595/gradbridge/tree/main/frontend/src/api"
click node_frontend_state "https://github.com/iftekhartamim595/gradbridge/tree/main/frontend/src/contexts"
click node_frontend_routes "https://github.com/iftekhartamim595/gradbridge/tree/main/frontend/src/components"
click node_frontend_chat "https://github.com/iftekhartamim595/gradbridge/tree/main/frontend/src/components/chat"
click node_frontend_pages "https://github.com/iftekhartamim595/gradbridge/tree/main/frontend/src/pages"
click node_frontend_ai "https://github.com/iftekhartamim595/gradbridge/blob/main/frontend/src/components/AIInsights.jsx"

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_backend_config,node_backend_accounts,node_backend_profiles,node_backend_search,node_backend_projects,node_backend_community,node_backend_jobs,node_backend_mentorship,node_backend_chat,node_backend_notifications,node_backend_ai,node_backend_utils toneBlue
class node_frontend_app,node_frontend_api,node_frontend_state,node_frontend_routes,node_frontend_chat,node_frontend_pages,node_frontend_ai toneAmber
```

## Components

### Backend

Django monolith and feature apps

- [Core config](https://github.com/iftekhartamim595/gradbridge/tree/main/backend/config): django wiring · Settings, routing, ASGI/WSGI, auth, CORS, Channels, deployment · `backend/config`
- [Accounts](https://github.com/iftekhartamim595/gradbridge/tree/main/backend/accounts): identity · Custom user model, roles, approval flow, OAuth, permissions · `backend/accounts`
- [Profiles](https://github.com/iftekhartamim595/gradbridge/tree/main/backend/profiles): profile domain · Student and alumni profiles, certificates, visibility, signals · `backend/profiles`
- [Search](https://github.com/iftekhartamim595/gradbridge/tree/main/backend/search): discovery · Filtered alumni discovery and matching queries · `backend/search`
- [Projects](https://github.com/iftekhartamim595/gradbridge/tree/main/backend/projects): portfolio domain · User work samples and project records · `backend/projects`
- [Community](https://github.com/iftekhartamim595/gradbridge/tree/main/backend/community): social feed · Broader social or feed-style interactions · `backend/community`
- [Jobs](https://github.com/iftekhartamim595/gradbridge/tree/main/backend/jobs): hiring domain · Job posts, recruiter fields, applications, utilities · `backend/jobs`
- [Mentorship](https://github.com/iftekhartamim595/gradbridge/tree/main/backend/mentorship): workflow · Mentorship requests and lifecycle management · `backend/mentorship`
- [Chat](https://github.com/iftekhartamim595/gradbridge/tree/main/backend/chat): realtime messaging · WebSocket consumers, routing, middleware, and message history · `backend/chat`
- [Notifications](https://github.com/iftekhartamim595/gradbridge/tree/main/backend/notifications): event notifications · Notification records and signal-driven event generation · `backend/notifications`
- [AI insights](https://github.com/iftekhartamim595/gradbridge/tree/main/backend/ai_insights): llm analysis · Resume analysis, OpenRouter integration, scoring and recommendations · `backend/ai_insights`
- [Shared utils](https://github.com/iftekhartamim595/gradbridge/tree/main/backend/utils): cross-cutting helpers · Email delivery and shared validation helpers · `backend/utils`

### Frontend

React/Vite SPA and client state

- [SPA shell](https://github.com/iftekhartamim595/gradbridge/blob/main/frontend/src/App.jsx): react app · Vite application composition and route assembly · `frontend/src/App.jsx`
- [API layer](https://github.com/iftekhartamim595/gradbridge/tree/main/frontend/src/api): client services · Centralized HTTP clients for backend access · `frontend/src/api`
- [Client state](https://github.com/iftekhartamim595/gradbridge/tree/main/frontend/src/contexts): react contexts · Auth, chat, and modal shared state · `frontend/src/contexts`
- [Route guards](https://github.com/iftekhartamim595/gradbridge/tree/main/frontend/src/components): access control · Private and recruiter-approved client-side route protection · `frontend/src/components`
- [Chat UI](https://github.com/iftekhartamim595/gradbridge/tree/main/frontend/src/components/chat): messaging UI · Chat window and socket hook for live messaging · `frontend/src/components/chat`
- [Role pages](https://github.com/iftekhartamim595/gradbridge/tree/main/frontend/src/pages): screen modules · Student, alumni, recruiter, admin, jobs, community, mentorship, search, and profile screens · `frontend/src/pages`
- [AI pages](https://github.com/iftekhartamim595/gradbridge/blob/main/frontend/src/components/AIInsights.jsx): analysis UI · Resume analysis and insights screens · `frontend/src/components/AIInsights.jsx`

## Connections

- Core config → Accounts: auth wiring · Installs user model, JWT, OAuth, and permissions into the Django stack
- Core config → Chat: channels · ASGI and websocket routing enable live chat
- Core config → Notifications: events · Global settings support signal-driven notification flow
- Accounts → Profiles: role base · Profile visibility and branching depend on approved user roles
- Profiles → Search: visibility · Discovery uses profile data and visibility controls
- Profiles → Projects: showcase data · Projects complement profile enrichment and portfolio views
- Accounts → Jobs: recruiter gate · Job publishing and hiring flows depend on account role and approval
- Accounts → Mentorship: access rules · Mentorship participation follows identity and role checks
- Profiles → Community: identity data · Community features are shaped by user profile information
- Chat → Notifications: activity alerts · Messaging events can surface as notifications
- Profiles → Notifications: signals · Profile changes emit notification side effects
- Jobs → Notifications: applications · Job and application events can trigger notifications
- Mentorship → Notifications: request events · Mentorship lifecycle changes can trigger notifications
- AI insights → Shared utils: validation · Resume processing reuses shared input checks and email helpers indirectly
- SPA shell → Route guards: renders · The SPA composes protected and role-aware screens
- SPA shell → Client state: shared state · Contexts provide auth, chat, and modal state across the app
- SPA shell → API layer: data access · Pages go through centralized API clients
- Client state → Chat UI: socket state · Chat context and hook support live conversation updates
- API layer → Accounts: auth API · Login, registration, and approval flows call account endpoints
- API layer → Profiles: profile API · Profile views and edits use REST endpoints
- API layer → Search: discovery API · Alumni and student search is fetched from the backend
- API layer → Jobs: jobs API · Hiring screens interact with job and application endpoints
- API layer → Mentorship: mentorship API · Mentorship pages use request and lifecycle endpoints
- API layer → Community: community API · Social feed interactions are loaded through the API layer
- API layer → Notifications: notifications API · Notification lists and status are fetched from the backend
- API layer → AI insights: analysis API · Resume analysis uploads are submitted to AI endpoints
- Chat UI → Chat: websocket · Chat UI subscribes to live messages over Channels
- Role pages → API layer: uses · Role-specific screens consume the shared client layer
- Role pages → Chat UI: messages · Messages and inbox screens embed the chat UI
- AI pages → AI insights: resume analysis · AI insights screens call the resume analysis backend