Personalised course guidance for students. One admissions workspace for institutions.
AdmitFlow helps students explore courses through a natural Telegram conversation. It learns from their interests, educational background and goals, introduces relevant options they may not know about, and answers questions using institution reference material. Admissions teams see the conversation, shared details and next steps in an authenticated web dashboard.
Features · Architecture · AI workflow · Tech stack · Getting started · Documentation
Choosing a course often starts with an incomplete picture. A student may know only familiar degree names, feel unsure about their interests, or struggle to understand entry requirements. Institution websites and documents contain useful information, but students still need help connecting it to their own situation.
Admissions teams face the other side of that conversation: repeated questions, scattered inquiries and students who have to explain their background again when staff take over.
Give each student a conversation that helps them make an informed choice, while retaining useful context for the institution.
AdmitFlow adapts its next question to what the student has already shared. It accepts free text and uses contextual options when they make answering easier. A student with a clear choice can move ahead; an uncertain student can explore relevant alternatives at their pace. If the catalogue does not offer a suitable course, the assistant explains the gap instead of pushing an unrelated option.
The intended benefit is less repetitive information collection and more useful admissions conversations. Customer demand, conversion gains and time savings have not yet been measured.
- Adaptive course guidance: explore interests, background, study goals and practical constraints without a fixed interview or compulsory quiz.
- Relevant course discovery: compare familiar and less familiar options using the institution's catalogue and the student's explicit preferences.
- Context and corrections: update earlier answers without restarting the conversation.
- Grounded answers: ask about institution information drawn from indexed documents; missing supporting evidence leads to an honest fallback.
- Application support: for configured admissions offerings, reuse supplied details, collect missing information and require review before submission.
- Clear controls: typing feedback, fresh conversation reset, optional deeper exploration and staff help when requested or necessary.
- Admissions workspace: inspect inquiries, transcripts, guidance evidence and application progress in one authenticated dashboard.
- Knowledge library: upload files or folders, track indexing, retry failed uploads and search reference passages. Supports digital PDF, DOCX and text, including Markdown/CSV.
- Catalogue management: manage courses, batches, eligibility rules, application fees and discounts. Published reference records remain separate from admissions offerings.
- Staff collaboration: take over a conversation, review co-pilot drafts and explicitly resume automation when the staff interaction ends.
- Applications and payment operations: review applications, inspect payment states and reconcile supported provider records through controlled actions.
- Follow-ups and reporting: consent-aware reminders, analytics, CSV/Excel exports, notifications and signed outbound webhooks.
- Administration and privacy: staff roles, tenant-scoped access, audit records, erasure and retention controls.
- A student starts a private conversation with the institution's Telegram bot.
- The assistant uses what they share to decide whether to clarify, explore, compare or answer a question. It does not require the same sequence from every student.
- Course suggestions connect explicit interests and background to catalogue information. Code checks configured academic rules separately from interest exploration.
- Questions about the institution use retrieved reference material. The assistant avoids inventing unavailable courses, prices, admission decisions or seat reservations.
- For an actual admissions offering, the student can continue through eligibility and application review. Staff receive the saved context when intervention is needed.
The current adaptive guidance experience uses English. Its research-informed approach uses CIP/CASVE decision support, tentative activity-interest themes and OARS listening principles. Optional deeper exploration is not a validated psychometric or aptitude test. See the research and implementation mapping.
flowchart TD
Student[Student] <-->|Private chat| Telegram[Telegram Bot API]
Telegram <--> Receiver[Institution receiver and reply delivery]
Receiver -->|Durable inbox| Database[(PostgreSQL and pgvector)]
Receiver --> Queue[(Redis task queues)]
Queue --> Worker[TaskIQ conversation worker]
Worker --> Engine[Conversation engine and business rules]
Engine <--> AI[OpenAI API]
Engine <--> Database
Engine -->|Validated reply outbox| Receiver
Staff[Institution staff] --> Dashboard[Next.js dashboard]
Dashboard -->|Authenticated same-origin API| API[FastAPI]
API <--> Database
API --> Queue
Files[Institution reference files] --> API
Queue --> Knowledge[Dedicated knowledge worker]
Knowledge --> Parser[Docling and document parsers]
Parser --> Embeddings[OpenAI embeddings]
Embeddings --> Database
Scheduler[Follow-up and recovery scheduler] --> Queue
API <--> Payments[Razorpay integration]
The receiver binds a bot to an institution and persists accepted updates with polling checkpoints. Workers process the saved conversation and commit state with a reply outbox. Delivery tracks sent, failed and uncertain outcomes rather than blindly repeating ambiguous sends. A separate serial knowledge worker keeps document parsing away from interactive conversation processing.
The dashboard proxies requests through the same origin to FastAPI. PostgreSQL stores institution-scoped records and vector embeddings; Redis supports background work and shared operational controls.
| Responsibility | Approach |
|---|---|
| Understand a message | OpenAI produces typed decisions and extracts explicitly stated facts and preferences. |
| Guide a student | A bounded planning step uses conversation evidence and refreshed catalogue checks to choose a useful response. |
| Find reference material | OpenAI embeddings support tenant- and course-scoped semantic retrieval in pgvector. |
| Rank and answer | OpenAI reranks eligible passages and selects supporting quotations; relevance and quotation checks constrain the answer. |
| Make consequential changes | Application code controls eligibility, fees, access, selections and application/payment state. |
OpenAI is the active hosted AI provider. Model roles are configurable in
backend/.env.example; the current defaults use gpt-4.1-mini and
text-embedding-3-small. No model fine-tuning or additional hosted inference service is
required. Retrieved documents and student messages are treated as untrusted input.
flowchart LR
Upload[File or folder upload] --> Extract[Extract text, headings and tables]
Extract --> Chunk[Create contextual passages]
Chunk --> Embed[Generate embeddings]
Embed --> Index[(Tenant-scoped pgvector index)]
Question[Student question] --> Retrieve[Retrieve relevant passages]
Index --> Retrieve
Retrieve --> Rank[Rerank supporting evidence]
Rank --> Check[Validate supporting quotation]
Check --> Answer[Grounded answer or abstention]
Digital PDF parsing uses offline CPU Docling layout/table models. DOCX and text extraction preserve useful structure. OCR is outside this version, so scanned pages need a searchable replacement. Original uploaded files are encrypted; extracted reference text is stored in the institution-scoped database. Sources remain available internally and in staff search without adding document filenames to every student reply.
| Layer | Technologies and tools | Purpose |
|---|---|---|
| Student channel | Telegram Bot API | Private chat, contextual buttons and typing feedback |
| Web dashboard | Next.js, React, TypeScript | Staff workspace and same-origin API proxy |
| API and validation | Python 3.12+, FastAPI, Pydantic | Authenticated endpoints and typed contracts |
| Conversation | Async Python conversation engine, OpenAI API | Adaptive guidance, memory and bounded decisions |
| Data and retrieval | PostgreSQL, pgvector, SQLAlchemy, Alembic | Tenant records, vector search and migrations |
| Background processing | Redis, TaskIQ | Conversation, document and follow-up jobs |
| Document understanding | Docling, PDF/DOCX/text parsers | Offline layout/table extraction and structured ingestion |
| Payments | Razorpay | Test credential provisioning, payment links and signed webhook handling |
| Public reference discovery | SerpAPI and official source pages | Discover JAIN Kochi programme information for the local reference catalogue |
| Quality checks | pytest, Ruff, strict mypy, TypeScript, Playwright | Logic, database, typing and browser verification |
| Local packaging and CI | uv, npm, Docker Compose, GitHub Actions | Reproducible environments and protected-branch checks |
Legacy WhatsApp compatibility remains in source with the feature disabled by default. Telegram is the active product channel. Optional observability providers are not prerequisites for the local stack.
- Python 3.12+ and
uv. - A supported Node.js release and
npmfor the dashboard; CI uses Node 22 and the container build uses Node 24. - Docker with Compose for the packaged stack and disposable database integration tests.
- An OpenAI API key for live guidance, embeddings and reranking.
- An institution-owned Telegram bot token for a live student conversation.
This starts a separate local workspace with synthetic sample courses and a generated staff account. It does not copy the owner's active database, JAIN reference import or credentials.
git clone https://github.com/Shan091/admitflow.git
cd admitflow/backend
uv sync --frozen
uv run python -m src.scripts.configure_compose
cd ..The configuration command creates a private root .env and refuses to overwrite an existing
file. Add your own OPENAI_API_KEY to that file before starting model-dependent features.
Then run from the repository root:
docker compose config --quiet
docker compose up --build -d --wait
docker compose cp bootstrap:/run/admitflow/.demo-credentials.json backend/.demo-compose-credentials.json| Service | Local address |
|---|---|
| Staff dashboard | http://127.0.0.1:13000 |
| API documentation | http://127.0.0.1:18000/docs |
| API readiness | http://127.0.0.1:18000/ready |
Sign in using the institution code, email and password in the generated private credential file. Keep it out of Git and shared screenshots.
To enable Telegram in this isolated workspace, configure a separate test bot in the root
.env, then run:
docker compose --profile telegram up -d receiverOnly one receiver should poll a bot. Follow the Compose runbook for configuration, verification, restart and recovery details.
Use the native runtime guide for PostgreSQL/Redis setup,
private backend/.env configuration, migrations, institution provisioning and all required
processes. The native dashboard uses port 3000, and the API uses port 8000.
The main entry points, run in separate terminals, are:
# From backend/, after configuring data services and applying migrations:
uv run uvicorn src.main:app --host 127.0.0.1 --port 8000
uv run taskiq worker src.tasks.broker:broker src.tasks.telegram src.tasks.followups src.tasks.integrations --workers 1
uv run taskiq worker src.tasks.knowledge:broker src.tasks.knowledge --workers 1 --max-async-tasks 1
uv run python -m src.telegram.receiver --institution-code demo
uv run python -m src.scripts.scheduler
# From frontend/:
npm ci
npm run devPrepare document models before native PDF ingestion using
uv run python -m src.scripts.prepare_document_models from backend/.
See backend setup for manual institution/admin provisioning.
| Setting | Used for |
|---|---|
DATABASE_URL, REDIS_URL |
Database and background services |
PII_ENCRYPTION_KEY, PHONE_HASH_KEY |
Application encryption and identifier lookup/signing |
OPENAI_API_KEY |
Live model requests and embeddings |
TELEGRAM_BOT_TOKEN, TELEGRAM_INSTITUTION_CODE |
Institution bot binding |
RAZORPAY_KEY_ID, RAZORPAY_KEY_SECRET, RAZORPAY_WEBHOOK_SECRET |
Optional institution payment integration |
PAYMENTS_LIVE_ENABLED |
Explicit live-payment guard; keep false for local testing |
Use the environment template for defaults and optional settings.
The Compose root .env and native backend/.env are separate configurations. Never commit
secrets or expose them in the frontend. Retain encryption keys with database backups.
| Command | Purpose |
|---|---|
/start |
Start an English admissions conversation |
/guide |
Resume course guidance |
/courses |
Browse catalogue options |
/assessment |
Opt into deeper exploratory guidance |
/apply |
Start or resume an application for a configured admissions offering |
/pause |
Keep an unfinished application draft for later |
/reset |
Confirm a fresh conversational context |
/human |
Explicitly request staff help |
/followups, /stop |
Manage reminder consent |
A reset excludes earlier chat from future model context and clears unfinished exploration or a draft. It preserves institutional history, submitted applications/payments, reminder choices and active staff requests. It is not a data-erasure command.
The platform includes adaptive guidance, institution knowledge, applications/review, payment integration and a broader staff workspace. STATUS.md separates implemented capabilities, dated verification and unfinished production acceptance. Technical records retain source-specific checks; no old count or recording is a current readiness guarantee.
# From backend/:
bash scripts/verify.sh
uv run pytest -m integration
# From frontend/:
npm ci
npm run lint
npm run buildDefault tests fake external providers. Integrations need disposable Docker services; live model/browser/handset checks have separate prerequisites and authority. See the testing guide.
Real admissions require an authorised institution's maintained catalogue, intakes, rules, fees and operating policy. The tracked JAIN Kochi public-reference snapshot supports independent information/development and does not establish university representation, prices, seats or admission authority. Synthetic seeds and the legacy reference-course sample application/test-payment mode remain explicitly development-only.
See development modes and data/model provenance. Latest-flow test-card/handset acceptance, production operations and a real institution pilot remain open. Public deployment has not been performed and requires the owner's instruction.
Tenant-scoped queries/constraints, staff roles/sessions, sensitive-field encryption, signed controls, durable delivery, audit, reminder consent and retention/deletion are part of the product. Prices and academic rules come from maintained records. Payment and eligibility do not by themselves grant admission. Missing evidence and uncertain provider outcomes remain visible.
See security and production for hosting, backups/restores, monitoring, privacy policy and release/rollback requirements.
Start with PRODUCT.md, SPEC.md, STATUS.md, then the documentation map. Implementation work stays in tasks/plan.md and tasks/todo.md. Architecture decisions, guidance research, engineering guides and verification are maintained here. The context reconciliation captures inherited product decisions locally; no other repository is required.
Read AGENTS.md and the development lifecycle. Use a feature branch, meaningful checks, adversarial review and green CI before merging. Protect tenant authority, applicant data and payments. Report reproducible issues without credentials or private applicant content.
Shan is the owner and solo contributor. Project source uses the MIT License. Dependencies, model assets and public reference material retain their respective terms.