# tanvir-hannan-anik/diu-admission-portal architecture

> Architecture diagram of the GitHub repository tanvir-hannan-anik/diu-admission-portal, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tanvir-hannan-anik/diu-admission-portal
- Repository: https://github.com/tanvir-hannan-anik/diu-admission-portal

## Overview

1. **Overall shape**
   - This repo is a three-service system: a React frontend, a Spring Boot API, and a Python Flask AI service.
   - The frontend talks mainly to the Spring Boot backend for business workflows, and directly or indirectly to the Python service for AI-heavy interactions.

2. **Frontend boundary: user-facing SPA**
   - `frontend-react/` is a React 18 single-page app with two major surfaces:
     - the public/student experience: admission chatbot, Smart Advisor, jobs, scholarship, proctoring, login/register flows
     - the staff/admin experience under `/admin`: CRM pipeline, leads, applications, analytics, audit logs, role management
   - It contains API client modules per domain, plus shared UI components, auth hooks, and voice support via the browser Web Speech API.

3. **Spring Boot boundary: core application gateway**
   - `backend-spring-boot/` is the central REST backend and persistence layer.
   - It owns authentication, authorization, most CRUD domains, admissions, student records, payments, scholarships, notices, leads, chat logs, and admin dashboards.
   - Controllers are grouped by business area, and the service layer contains orchestration logic such as admissions, lead handling, chat logging, audit logging, and AI request forwarding.

4. **Authentication and security**
   - Spring Boot uses JWT-based stateless authentication with Spring Security.
   - Admin functionality is role-protected, and there is explicit audit logging around sensitive operations.
   - The frontend has separate admin auth handling, while the backend enforces the actual access control boundary.

5. **Python AI service boundary**
   - `backend-python/` is a Flask microservice dedicated to AI, retrieval, scraping, and knowledge processing.
   - It is not the primary transactional backend; instead it handles chat-style AI endpoints, knowledge ingestion, semantic search, and job/tuition/faculty intelligence.
   - Spring Boot calls into this service through a dedicated client, so the AI layer stays isolated from the core business API.

6. **RAG knowledge pipeline**
   - The Python service is built around retrieval-augmented generation.
   - Incoming questions are normalized, embedded, matched against a Qdrant vector collection, and then answered by Groq-hosted LLMs using retrieved context.
   - The knowledge base is fed from multiple sources: curated JSON docs, department flyers, PDFs, live scraped pages, and seeded FAQ/knowledge records.

7. **Ingestion and synchronization subsystem**
   - The Python app includes scraping, OCR/content extraction, incremental indexing, change detection, semantic cache, and scheduled sync services.
   - Supporting scripts build the RAG index, ingest departments, seed FAQs, and sync faculty/source data.
   - This subsystem is the data-preparation side of the AI architecture, distinct from runtime chat responses.

8. **Data storage layer**
   - The operational database is PostgreSQL via Supabase in production, with local SQL/init scripts and Supabase migrations in the repo.
   - Spring Boot stores the transactional domain data there: users, leads, applications, payments, notifications, chats, and similar records.
   - The Python AI service also persists operational metadata such as query logs, sync state, cache state, and knowledge chunking-related records.

9. **Vector and semantic retrieval layer**
   - The AI stack uses Qdrant Cloud as the vector store for the DIU knowledge base.
   - Embeddings are generated with Google Gemini, while answer generation is handled by Groq models.
   - The architecture separates semantic retrieval from relational persistence: Postgres handles business data, Qdrant handles similarity search.

10. **External integrations**
   - PostHog and Microsoft Clarity are pulled into the admin analytics experience.
   - JSearch/RapidAPI is used for live job listings.
   - Gmail SMTP is used for email workflows in the Spring Boot backend.
   - Firebase is used on the frontend for Google OAuth authentication.

11. **Admin/CRM and analytics flow**
   - Student and visitor interactions are turned into admin-visible records such as leads, chat logs, applications, and follow-up items.
   - Analytics data comes from external visitor tools and is surfaced through Spring Boot endpoints to the admin dashboard.
   - This is a clear boundary between operational student workflows and staff oversight/management workflows.

12. **Runtime and deployment topology**
   - The repo is designed to run locally with Docker Compose and also deploy to Render.
   - Each major service has its own containerization setup: React, Spring Boot, and Python Flask.
   - The architecture assumes service-to-service HTTP communication, not a monolith.

13. **Shared domain model vs. AI knowledge model**
   - The Spring Boot service defines structured business entities such as users, admissions, leads, payments, notices, scholarships, and chat logs.
   - The Python service defines a separate knowledge model centered on chunks, documents, sources, cache, sync, and embeddings.
   - This split is important for diagramming: one side is transactional university operations, the other is retrieval and language intelligence.

14. **Supporting assets and operational tooling**
   - `database/` and `supabase/` hold schema and migration artifacts.
   - `scripts/` in the Python service are used for maintenance jobs and knowledge-base preparation.
   - Workflow files and deployment configs indicate the project is intended for automated sync, scheduled ingestion, and repeatable multi-service deployment.

15. **Mental model for a diagram**
   - Draw the React SPA at the edge, feeding requests into Spring Boot for normal app and admin flows.
   - Draw Spring Boot connected to Postgres/Supabase, and to the Python AI service for AI-specific endpoints.
   - Draw the Python service connected to Qdrant and external AI APIs, with background ingestion/sync sources feeding its knowledge base.
   - Add PostHog/Clarity and JSearch as external integrations used through the backend/admin surfaces.

Main entry points: [`backend-spring-boot/src/main/java/com/university/UniversityAutomationApplication.java`](https://github.com/tanvir-hannan-anik/diu-admission-portal/blob/main/backend-spring-boot/src/main/java/com/university/UniversityAutomationApplication.java) (REST API), [`frontend-react/src/App.js`](https://github.com/tanvir-hannan-anik/diu-admission-portal/blob/main/frontend-react/src/App.js) (React App), [`backend-python/app/services/rag_service.py`](https://github.com/tanvir-hannan-anik/diu-admission-portal/blob/main/backend-python/app/services/rag_service.py) (RAG Pipeline), [`backend-python/app/services/ingestion_service.py`](https://github.com/tanvir-hannan-anik/diu-admission-portal/blob/main/backend-python/app/services/ingestion_service.py) (Ingestion Sync)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React SPA"]
  node_frontend_shell["React App<br/>spa shell<br/>[App.js]"]
  node_frontend_public["Public UI<br/>student portal"]
  node_frontend_admin["Admin Portal<br/>admin console"]
  node_frontend_services["API Clients<br/>frontend services"]
  node_frontend_auth["Auth & Voice<br/>hooks and config"]
end

subgraph group_spring["Spring Boot API"]
  node_spring_api["REST API<br/>backend gateway"]
  node_spring_security["Security<br/>jwt auth"]
  node_spring_auth["Auth & Users<br/>identity service<br/>[AuthService.java]"]
  node_spring_admissions["Admissions<br/>workflow service"]
  node_spring_ops["Student Ops<br/>domain services"]
  node_spring_ai_proxy["AI Proxy<br/>service client"]
  node_spring_audit["Admin Ops<br/>audit and analytics<br/>[AuditService.java]"]
  node_spring_data[("Postgres Data<br/>jpa models")]
end

subgraph group_python["Flask AI Service"]
  node_python_api["Flask App<br/>ai microservice<br/>[main.py]"]
  node_python_rag["RAG Pipeline<br/>retrieval pipeline<br/>[rag_service.py]"]
  node_python_ingest["Ingestion Sync<br/>pipeline services"]
  node_python_knowledge[("Knowledge Store<br/>repos and models")]
end

subgraph group_infra["Data & Integrations"]
  node_python_external_ai(("LLM & Embeddings<br/>ai providers<br/>[groq_service.py]"))
  node_infra_db[("Supabase Postgres<br/>relational store<br/>[init.sql]")]
  node_infra_vector[("Qdrant<br/>vector store")]
  node_infra_integrations(("External Services<br/>third-party integrations<br/>[firebase.js]"))
end

node_frontend_shell -->|"renders"| node_frontend_public
node_frontend_shell -->|"renders"| node_frontend_admin
node_frontend_shell -->|"uses"| node_frontend_services
node_frontend_shell -->|"depends on"| node_frontend_auth
node_frontend_services -->|"calls"| node_spring_api
node_frontend_services -.->|"calls AI"| node_python_api
node_frontend_auth -->|"uses"| node_infra_integrations
node_spring_api -->|"guards with"| node_spring_security
node_spring_api -->|"routes auth"| node_spring_auth
node_spring_api -->|"orchestrates"| node_spring_admissions
node_spring_api -->|"serves"| node_spring_ops
node_spring_api -->|"forwards"| node_spring_ai_proxy
node_spring_api -->|"logs"| node_spring_audit
node_spring_api -->|"persists"| node_spring_data
node_spring_data -->|"stores in"| node_infra_db
node_spring_ai_proxy -->|"HTTP client"| node_python_api
node_python_api -->|"executes"| node_python_rag
node_python_api -->|"manages"| node_python_ingest
node_python_rag -->|"reads"| node_python_knowledge
node_python_rag -->|"searches"| node_infra_vector
node_python_rag -->|"generates with"| node_python_external_ai
node_python_ingest -->|"writes"| node_python_knowledge
node_python_ingest -->|"syncs to"| node_infra_db
node_python_ingest -->|"indexes"| node_infra_vector
node_spring_audit -->|"pulls analytics"| node_infra_integrations
node_spring_ops -->|"uses external APIs"| node_infra_integrations

click node_frontend_shell "https://github.com/tanvir-hannan-anik/diu-admission-portal/blob/main/frontend-react/src/App.js"
click node_frontend_public "https://github.com/tanvir-hannan-anik/diu-admission-portal/tree/main/frontend-react/src/components"
click node_frontend_admin "https://github.com/tanvir-hannan-anik/diu-admission-portal/tree/main/frontend-react/src/admin"
click node_frontend_services "https://github.com/tanvir-hannan-anik/diu-admission-portal/tree/main/frontend-react/src/services"
click node_frontend_auth "https://github.com/tanvir-hannan-anik/diu-admission-portal/tree/main/frontend-react/src/hooks"
click node_spring_api "https://github.com/tanvir-hannan-anik/diu-admission-portal/blob/main/backend-spring-boot/src/main/java/com/university/UniversityAutomationApplication.java"
click node_spring_security "https://github.com/tanvir-hannan-anik/diu-admission-portal/tree/main/backend-spring-boot/src/main/java/com/university/security"
click node_spring_auth "https://github.com/tanvir-hannan-anik/diu-admission-portal/blob/main/backend-spring-boot/src/main/java/com/university/service/AuthService.java"
click node_spring_admissions "https://github.com/tanvir-hannan-anik/diu-admission-portal/blob/main/backend-spring-boot/src/main/java/com/university/service/AdmissionService.java"
click node_spring_ops "https://github.com/tanvir-hannan-anik/diu-admission-portal/tree/main/backend-spring-boot/src/main/java/com/university/controller"
click node_spring_ai_proxy "https://github.com/tanvir-hannan-anik/diu-admission-portal/blob/main/backend-spring-boot/src/main/java/com/university/service/PythonServiceClient.java"
click node_spring_audit "https://github.com/tanvir-hannan-anik/diu-admission-portal/blob/main/backend-spring-boot/src/main/java/com/university/service/AuditService.java"
click node_spring_data "https://github.com/tanvir-hannan-anik/diu-admission-portal/tree/main/backend-spring-boot/src/main/java/com/university/model/entity"
click node_python_api "https://github.com/tanvir-hannan-anik/diu-admission-portal/blob/main/backend-python/main.py"
click node_python_rag "https://github.com/tanvir-hannan-anik/diu-admission-portal/blob/main/backend-python/app/services/rag_service.py"
click node_python_ingest "https://github.com/tanvir-hannan-anik/diu-admission-portal/blob/main/backend-python/app/services/ingestion_service.py"
click node_python_knowledge "https://github.com/tanvir-hannan-anik/diu-admission-portal/tree/main/backend-python/app/repositories"
click node_python_external_ai "https://github.com/tanvir-hannan-anik/diu-admission-portal/blob/main/backend-python/app/services/groq_service.py"
click node_infra_db "https://github.com/tanvir-hannan-anik/diu-admission-portal/blob/main/database/init.sql"
click node_infra_vector "https://github.com/tanvir-hannan-anik/diu-admission-portal/blob/main/backend-python/app/services/vector_store_service.py"
click node_infra_integrations "https://github.com/tanvir-hannan-anik/diu-admission-portal/blob/main/frontend-react/src/config/firebase.js"

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_shell,node_frontend_public,node_frontend_admin,node_frontend_services,node_frontend_auth toneBlue
class node_spring_api,node_spring_security,node_spring_auth,node_spring_admissions,node_spring_ops,node_spring_ai_proxy,node_spring_audit,node_spring_data toneAmber
class node_python_api,node_python_rag,node_python_ingest,node_python_knowledge toneMint
class node_python_external_ai,node_infra_db,node_infra_vector,node_infra_integrations toneRose
```

## Components

### React SPA

User-facing single-page app with public and admin surfaces

- [React App](https://github.com/tanvir-hannan-anik/diu-admission-portal/blob/main/frontend-react/src/App.js): spa shell · Entry point for the public and admin UI · `frontend-react/src/App.js`
- [Public UI](https://github.com/tanvir-hannan-anik/diu-admission-portal/tree/main/frontend-react/src/components): student portal · Admissions, jobs, scholarships, proctoring, and student flows · `frontend-react/src/components`
- [Admin Portal](https://github.com/tanvir-hannan-anik/diu-admission-portal/tree/main/frontend-react/src/admin): admin console · CRM, analytics, audit, users, and pipeline management · `frontend-react/src/admin`
- [API Clients](https://github.com/tanvir-hannan-anik/diu-admission-portal/tree/main/frontend-react/src/services): frontend services · Domain-specific API modules for auth, admissions, AI, leads, notices, and payments · `frontend-react/src/services`
- [Auth & Voice](https://github.com/tanvir-hannan-anik/diu-admission-portal/tree/main/frontend-react/src/hooks): hooks and config · Auth state, protected routes, Firebase OAuth, and browser speech support · `frontend-react/src/hooks`

### Spring Boot API

Transactional backend, security, and persistence orchestration

- [REST API](https://github.com/tanvir-hannan-anik/diu-admission-portal/blob/main/backend-spring-boot/src/main/java/com/university/UniversityAutomationApplication.java): backend gateway · Main application backend for business workflows · `backend-spring-boot/src/main/java/com/university/UniversityAutomationApplication.java`
- [Security](https://github.com/tanvir-hannan-anik/diu-admission-portal/tree/main/backend-spring-boot/src/main/java/com/university/security): jwt auth · Stateless JWT authentication and role-protected access control · `backend-spring-boot/src/main/java/com/university/security`
- [Auth & Users](https://github.com/tanvir-hannan-anik/diu-admission-portal/blob/main/backend-spring-boot/src/main/java/com/university/service/AuthService.java): identity service · Login, registration, password setup, and user lifecycle · `backend-spring-boot/src/main/java/com/university/service/AuthService.java`
- [Admissions](https://github.com/tanvir-hannan-anik/diu-admission-portal/blob/main/backend-spring-boot/src/main/java/com/university/service/AdmissionService.java): workflow service · Admission applications and student onboarding · `backend-spring-boot/src/main/java/com/university/service/AdmissionService.java`
- [Student Ops](https://github.com/tanvir-hannan-anik/diu-admission-portal/tree/main/backend-spring-boot/src/main/java/com/university/controller): domain services · Leads, chat logs, payments, notices, scholarships, notifications, and student records · `backend-spring-boot/src/main/java/com/university/controller`
- [AI Proxy](https://github.com/tanvir-hannan-anik/diu-admission-portal/blob/main/backend-spring-boot/src/main/java/com/university/service/PythonServiceClient.java): service client · Forwards AI requests to the Python service · `backend-spring-boot/src/main/java/com/university/service/PythonServiceClient.java`
- [Admin Ops](https://github.com/tanvir-hannan-anik/diu-admission-portal/blob/main/backend-spring-boot/src/main/java/com/university/service/AuditService.java): audit and analytics · Audit logging, clarity/posthog integration, and admin dashboards · `backend-spring-boot/src/main/java/com/university/service/AuditService.java`
- [Postgres Data](https://github.com/tanvir-hannan-anik/diu-admission-portal/tree/main/backend-spring-boot/src/main/java/com/university/model/entity): jpa models · Transactional entities and repositories for users, leads, applications, payments, chats, and profiles · `backend-spring-boot/src/main/java/com/university/model/entity`

### Flask AI Service

RAG, ingestion, scraping, and semantic retrieval

- [Flask App](https://github.com/tanvir-hannan-anik/diu-admission-portal/blob/main/backend-python/main.py): ai microservice · AI and knowledge-processing HTTP service · `backend-python/main.py`
- [RAG Pipeline](https://github.com/tanvir-hannan-anik/diu-admission-portal/blob/main/backend-python/app/services/rag_service.py): retrieval pipeline · Question normalization, embeddings, retrieval, context compression, and answer generation · `backend-python/app/services/rag_service.py`
- [Ingestion Sync](https://github.com/tanvir-hannan-anik/diu-admission-portal/blob/main/backend-python/app/services/ingestion_service.py): pipeline services · Scraping, extraction, incremental indexing, sync, and scheduled refresh · `backend-python/app/services/ingestion_service.py`
- [Knowledge Store](https://github.com/tanvir-hannan-anik/diu-admission-portal/tree/main/backend-python/app/repositories): repos and models · Chunks, documents, sources, FAQs, query logs, cache, and sync metadata · `backend-python/app/repositories`

### Data & Integrations

Shared database, vector store, and external services

- [LLM & Embeddings](https://github.com/tanvir-hannan-anik/diu-admission-portal/blob/main/backend-python/app/services/groq_service.py): ai providers · Groq generation and Gemini embeddings · `backend-python/app/services/groq_service.py`
- [Supabase Postgres](https://github.com/tanvir-hannan-anik/diu-admission-portal/blob/main/database/init.sql): relational store · Primary SQL database and migrations · `database/init.sql`
- [Qdrant](https://github.com/tanvir-hannan-anik/diu-admission-portal/blob/main/backend-python/app/services/vector_store_service.py): vector store · Semantic retrieval index for knowledge chunks · `backend-python/app/services/vector_store_service.py`
- [External Services](https://github.com/tanvir-hannan-anik/diu-admission-portal/blob/main/frontend-react/src/config/firebase.js): third-party integrations · Firebase, Gmail SMTP, PostHog, Clarity, JSearch/RapidAPI, and browser analytics · `frontend-react/src/config/firebase.js`

## Connections

- React App → Public UI: renders · The SPA hosts the public student-facing surfaces
- React App → Admin Portal: renders · The SPA also hosts the admin portal routes
- React App → API Clients: uses · UI screens call domain API clients
- React App → Auth & Voice: depends on · Auth state and voice features are shared across the app
- API Clients → REST API: calls · Primary business and admin workflows go through the Spring backend
- API Clients → Flask App: calls AI · AI-heavy interactions reach the Python service directly or through the backend
- Auth & Voice → External Services: uses · Frontend auth includes Firebase OAuth and browser-based tracking/voice support
- REST API → Security: guards with · Requests are authenticated and authorized through JWT security
- REST API → Auth & Users: routes auth · Authentication and user lifecycle flows are handled in backend services
- REST API → Admissions: orchestrates · Admission workflows are coordinated in the service layer
- REST API → Student Ops: serves · Most CRUD and operational university domains are exposed here
- REST API → AI Proxy: forwards · AI prompts are proxied to the Python microservice
- REST API → Admin Ops: logs · Sensitive admin activity and analytics flows are audited
- REST API → Postgres Data: persists · Transactional entities and repositories back the business API
- Postgres Data → Supabase Postgres: stores in · Spring persists operational data in Postgres
- AI Proxy → Flask App: HTTP client · Spring calls the AI service over HTTP
- Flask App → RAG Pipeline: executes · Chat and search endpoints delegate to the RAG pipeline
- Flask App → Ingestion Sync: manages · Ingestion and sync routes manage knowledge refresh flows
- RAG Pipeline → Knowledge Store: reads · Retrieval uses stored knowledge chunks, docs, FAQs, logs, and cache metadata
- RAG Pipeline → Qdrant: searches · Semantic matching is performed in the vector index
- RAG Pipeline → LLM & Embeddings: generates with · Answers are composed using external LLM and embedding providers
- Ingestion Sync → Knowledge Store: writes · Scraping and indexing update the knowledge repositories
- Ingestion Sync → Supabase Postgres: syncs to · Operational metadata and sync state are stored in Postgres
- Ingestion Sync → Qdrant: indexes · Ingested content is embedded and pushed to Qdrant
- Admin Ops → External Services: pulls analytics · Admin analytics and monitoring integrate with external tracking tools
- Student Ops → External Services: uses external APIs · Jobs, email, and analytics features depend on third-party services