How tanvir-hannan-anik/diu-admission-portal works
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: UniversityAutomationApplication.java REST API · App.js React App · rag_service.py RAG Pipeline · ingestion_service.py Ingestion Sync
Components 21
React SPA
User-facing single-page app with public and admin surfaces
- React App · Entry point for the public and admin UI
frontend-react/src/App.js - Public UI · Admissions, jobs, scholarships, proctoring, and student flows
frontend-react/src/components - Admin Portal · CRM, analytics, audit, users, and pipeline management
frontend-react/src/admin - API Clients · Domain-specific API modules for auth, admissions, AI, leads, notices, and payments
frontend-react/src/services - Auth & Voice · 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 · Main application backend for business workflows
backend-spring-boot/src/main/java/com/university/UniversityAutomationApplication.java - Security · Stateless JWT authentication and role-protected access control
backend-spring-boot/src/main/java/com/university/security - Auth & Users · Login, registration, password setup, and user lifecycle
backend-spring-boot/src/main/java/com/university/service/AuthService.java - Admissions · Admission applications and student onboarding
backend-spring-boot/src/main/java/com/university/service/AdmissionService.java - Student Ops · Leads, chat logs, payments, notices, scholarships, notifications, and student records
backend-spring-boot/src/main/java/com/university/controller - AI Proxy · Forwards AI requests to the Python service
backend-spring-boot/src/main/java/com/university/service/PythonServiceClient.java - Admin Ops · Audit logging, clarity/posthog integration, and admin dashboards
backend-spring-boot/src/main/java/com/university/service/AuditService.java - Postgres Data · 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 · AI and knowledge-processing HTTP service
backend-python/main.py - RAG Pipeline · Question normalization, embeddings, retrieval, context compression, and answer generation
backend-python/app/services/rag_service.py - Ingestion Sync · Scraping, extraction, incremental indexing, sync, and scheduled refresh
backend-python/app/services/ingestion_service.py - Knowledge Store · 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 · Groq generation and Gemini embeddings
backend-python/app/services/groq_service.py - Supabase Postgres · Primary SQL database and migrations
database/init.sql - Qdrant · Semantic retrieval index for knowledge chunks
backend-python/app/services/vector_store_service.py - External Services · Firebase, Gmail SMTP, PostHog, Clarity, JSearch/RapidAPI, and browser analytics
frontend-react/src/config/firebase.js
Connections 26
- 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