Campus-Pulse-AI
About the project
π‘ CampusPulse AI
Twelve college WhatsApp groups. One feed you can trust.
An agentic AI system that reads all of a studentβs WhatsApp groups, filters the noise, extracts deadlines and tasks,
catches when an announcement changes, busts rumours with official sources, and answers questions with citations.
π Table of contents
- The problem
- The solution
- Features
- Screenshots
- System architecture
- The AI pipeline, stage by stage
- Rumor Shield, the innovation
- Live WhatsApp integration
- Ask Campus AI (RAG) and the Pulse chatbot
- Databases
- Authentication and security
- REST API
- Folder structure
- Getting started
- Testing and evaluation
- Tech stack
- Limitations and roadmap
π― The problem
A typical engineering student is in a dozen WhatsApp groups: class, section, placement cell, hackathon team, fest
committee, clubs. Important information gets lost:
| Pain point | What actually happens |
|---|---|
| Noise | A deadline is buried under 40 messages of βokβ, βthanksβ and π. |
| Duplicates | The same internship is forwarded to five groups. |
| Silent changes | A venue moves in one group; you only saw the original message in another. |
| Conflicts | The CR says Thursday, a classmate says Friday. Whoβs right? |
| Rumours | βI heard the mid-sem is postponed??β spreads faster than the professorβs correction. |
| Irrelevance | Half the announcements are for other years or branches. |
| Lost doubts | Someone asks βwhereβs the briefing?β and nobody answers, even though the answer is in another group. |
π‘ The solution
CampusPulse AI imports a studentβs groups (by linking their WhatsApp number or by uploading chat exports)
and runs every message through an agentic pipeline that produces one ranked, personal, trustworthy feed.
Core design rule: the original WhatsApp messages are the source of truth. AI organises and interprets them but
never silently replaces them. Every card, task and answer links back to the original message: its group, sender
and time.
β¨ Features
Core
| Feature | Description |
|---|---|
| π Todayβs Brief | One ranked feed across every group, scored with an explainable formula. Each card says why itβs here. |
| π§Ή Noise filter | βokβ, βthanksβ, emoji-only, system and deleted messages are marked as noise. They are kept, never deleted. |
| π·οΈ Classification | Category (academics, placements, hackathons, events, resources, faculty) and type (deadline, task, update, announcement, question, resource, chatter). |
| π Smart date extraction | βSunday 11:59 PMβ, βtmrwβ, β14 Octoberβ are resolved against the messageβs own timestamp. Ambiguous dates are flagged. |
| π Cross-group de-duplication | The same announcement in several groups becomes one card: βalso posted in β¦β. |
| π What Changed? engine | Detects when a newer message changes an earlier one and shows a field-level diff (old β new). It never assumes βlatest winsβ: unclear cases become conflicts. |
| π Is this for me? | Matches year, batch, branch, team and interests: relevant / not relevant / unknown. Nothing is hidden silently. |
| β My Tasks | Action items are generated automatically. When a deadline is extended in any group, the taskβs due date moves too. |
| ποΈ Deadlines + Crunch Radar | A 14-day workload forecast that highlights days where deadlines pile up and suggests when to start each task. |
| π Calendar export | One click β .ics file for Google Calendar, Outlook or Apple Calendar, with 24-hour reminders. |
| π PDF digests | Circulars and guidelines are split into page-referenced chunks, summarised and made searchable. |
Innovation and intelligence
| Feature | Description |
|---|---|
| π‘οΈ Rumor Shield | Every claim gets a verdict (Verified / Unverified / Contradicted) with a 0β100 trust score and evidence from official senders in any group. |
| π Cross-Group Doubt Solver | Finds questions nobody answered in their own group and answers them from other groups and documents. |
| π¬ Ask Campus AI | Retrieval-augmented answers from your messages and PDFs only, with citations. It says βI couldnβt find thisβ instead of inventing. |
| π€ Pulse chatbot | A floating rule-based assistant (no API key): βwhatβs due tomorrow?β, βany rumours?β, βmark SIH doneβ. |
Platform
| Feature | Description |
|---|---|
| π User accounts | Sign up and log in, with hashed passwords, secure sessions, login throttling and CSRF protection. |
| π€ Per-user isolation | Every account has its own database, files and WhatsApp session. |
| π² Live WhatsApp | Link your number by QR code (like WhatsApp Web), choose the groups, and new messages sync automatically. Your WhatsApp profile photo, name and βaboutβ appear on your profile. |
| π Light and dark themes | A professional two-tone dashboard (navy sidebar, light workspace) and a full dark mode. |
| π± Responsive | Works on phones with a slide-out menu. |
| π§ Optional LLM | Runs fully offline on the rule engine. Add an Anthropic or OpenAI-compatible key to refine classification and answers. |
πΌοΈ Screenshots
| Login | Dashboard (dark) |
|---|---|
| What Changed? | Rumor Shield |
| Pulse chatbot | Live WhatsApp |
| Deadlines and Crunch Radar | Mobile |
ποΈ System architecture
flowchart LR
subgraph Sources
WA[π² Linked WhatsApp number]
TXT[π Chat exports .txt]
PDF[π PDFs and circulars]
end
subgraph Bridge["whatsapp_bridge (Node.js)"]
BR[bridge.js<br/>whatsapp-web.js]
end
subgraph Backend["Flask backend (Python)"]
AUTH[Auth<br/>backend/auth.py]
ING[Ingestion<br/>parse Β· normalise Β· mask PII]
ORC[Agent orchestrator]
RAG[RAG engine]
BOT[Pulse chatbot]
API[REST API<br/>app.py]
end
subgraph Storage
ADB[(auth.db<br/>accounts)]
UDB[(users/ID/campuspulse.db<br/>per-user data)]
end
subgraph Frontend["Browser (HTML Β· CSS Β· JS)"]
UI[Dashboard SPA<br/>+ chat widget]
end
WA --> BR -->|JSON lines| ING
TXT --> ING
PDF --> ING
ING --> UDB
UDB --> ORC --> UDB
UDB --> RAG
UDB --> BOT
AUTH --> ADB
API --- AUTH & ORC & RAG & BOT
UI <-->|fetch + session cookie| API
| Layer | Responsibility | Key files |
|---|---|---|
| Ingestion | Parse Android/iOS exports and live bridge records, normalise, mask phone numbers, fingerprint | ingestion/ |
| Agent pipeline | Noise filter β classify β extract β trust β dedupe β change detection β personalise β prioritise | agent/ |
| Retrieval | BM25 search over messages and PDF pages, grounded answers with citations | rag/ |
| Backend | Auth, per-user data spaces, WhatsApp bridge manager, REST API, chatbot |
app.py, backend/
|
| Frontend | Login page and single-page dashboard with hash routing, themes and chat widget | web/ |
| Bridge | Links a WhatsApp number via QR and streams selected groups | whatsapp_bridge/ |
π§ The AI pipeline, stage by stage
The orchestrator (agent/orchestrator.py) runs every stage in order. The pipeline is idempotent: derived data
(analyses, events, changes) is rebuilt from the raw messages on every run, so re-running never duplicates anything,
while the studentβs task ticks are preserved.
flowchart TD
A[Raw messages] --> B[1 Β· Parse and normalise]
B --> C[2 Β· Noise filter]
C --> D[3 Β· Classify category and type]
D --> E[4 Β· Extract dates, venues, links, titles]
E --> F[5 Β· Rumor Shield: sender authority + hedge language]
F --> G[6 Β· Cross-group de-duplication]
G --> H[7 Β· Rumor Shield cross-check]
H --> I[8 Β· What Changed? engine]
I --> J[9 Β· Is this for me?]
J --> K[10 Β· Priority score + tasks]
K --> L[(Today's Brief Β· Tasks Β· Deadlines Β· Changes)]
1. Parse and normalise (ingestion/whatsapp_parser.py, normalizer.py)
- Supports Android (
10/10/26, 10:42 am - Name: text) and iOS ([10/10/26, 10:42:15 AM] Name: text), 12h and 24h clocks, and invisible Unicode characters (narrow no-break spaces, direction marks). - Lines without a header are joined to the previous message (multi-line messages).
- Classifies raw lines as
text,media,systemordeleted. -
Day/month disambiguation: a value above 12 must be the day; otherwise the configured order (
DMYfor India) applies. -
Privacy: 10+ digit phone numbers are masked (
β’β’β’β’β’β’3210) in senders and text. -
Fingerprint =
sha1(group | timestamp | sender | text)for exports,sha1("wa:" + WhatsApp message id)for live messages. A unique index means re-importing never duplicates.
2. Noise filter (agent/classifier.py)
Marks βokβ, βthanksβ, βnotedβ, emoji-only, system and deleted messages as noise. Media is kept (it may be a poster
or PDF). Noise stays visible in the group view behind a toggle; it is never deleted.
3. Classification (agent/classifier.py)
-
Category: keyword scoring per category, with the groupβs own category as a tie-breaker. Messages from faculty that match nothing else are labelled
faculty. -
Type: decision rules in priority order:
update(change verb + date or venue), thenquestion,deadline(deadline verb + date),task,resource,announcement,chatter.
4. Information extraction (agent/extractor.py)
-
Dates: relative (
today,tmrw,day after tomorrow), weekdays (Sunday,next Monday),12 October,Oct 12th,12/10. Relative dates resolve against the messageβs timestamp, not today. -
Times:
11:59 PM,5pm,17:00,noon,EOD. Deadlines without a time default to 23:59. - Update messages use the last date mentioned (βmoved from Tuesday to Wednesdayβ).
-
Venues:
Room 204,LT-2,Lab 5,Main Auditorium,venue: β¦. - Titles: the main sentence is chosen (skipping βGood morning everyone.β), then cut to a short title.
- Task titles: βSIH PPT submissionβ becomes βSubmit SIH PPTβ; βapplications closeβ becomes βApply for β¦β.
5β7. Trust and de-duplication
See Rumor Shield. De-duplication (agent/deduplicator.py) clusters two messages when:
| Rule | Condition |
|---|---|
| Shared link | Same URL and overlapping topic |
| Near-identical text |
SequenceMatcher ratio β₯ 0.85 (after removing βForwardedβ) |
| Same event | Same date and time, β₯ 2 shared entity tokens, topic Jaccard β₯ 0.5 |
8. The What Changed? engine (agent/change_detector.py)
Each meaningful message is matched to an existing event by topic:
- Topic tokens: words that describe what (dates, times, venues, hedges and change verbs removed).
-
Strong tokens: entity-like words: acronyms (
SIH,DBMS), proper nouns (Infosys) and head nouns (assignment,internship,briefing). - Match = β₯ 2 shared strong tokens, or 1 shared strong token with topic Jaccard β₯ 0.3.
Then a field-level diff is computed (date/time, venue, cancellation):
| New message is⦠| Result |
|---|---|
| Same details | Linked as duplicate or corroborates
|
| Different details and an explicit update (βmovedβ, βrescheduledβ, βextendedβ) | Change applied: current values updated, original kept, audit log written |
| Different details, not an explicit update | Conflict: both shown, nothing auto-resolved |
| A question or hearsay | Never modifies an event |
Tasks are linked to events, so an extended deadline automatically updates the task.
9. Is this for me? (agent/personalizer.py)
Extracts eligibility from the text and compares it with the profile:
| Signal | Example | Outcome for a 4th-year, 2027-batch CSE student |
|---|---|---|
| Year | βonly for 2nd year studentsβ | β not relevant: βMeant for 2nd year; you are in year 4β |
| Batch | βopen to 2028 batchβ | β not relevant |
| Branch | βCSE/IT/ECE onlyβ | β relevant |
| Team | βTeam Aagazβ | β relevant |
| Interests | category = placements | β relevant |
| Nothing stated | β | β unknown |
Not-relevant items stay in a collapsible βFiltered out for your profileβ section, with the reason.
10. Priority and Todayβs Brief (agent/planner.py)
P = 0.35Β·U + 0.30Β·D + 0.20Β·R + 0.15Β·C (each factor 0β100)
| Factor | Meaning | Scoring |
|---|---|---|
| U Urgency | Time to the (current) deadline | β€24h β 100, β€48h β 85, β€72h β 70, β€7d β 50, later β 20, passed β 0 |
| D Importance | Message type | deadline 90, task 80, update 78, announcement 55, resource 40, question 25 |
| R Relevance | Personalisation | relevant 100, unknown 60, not relevant 10 |
| C Confidence | Extraction confidence | 0β100 |
Hard rule: a verified deadline within 48 hours is lifted to β₯ 90. Rumours are capped at 30 and kept out of the
brief. Changed or conflicting events are lifted to β₯ 80. Items are grouped as Act on these first (β₯ 80),
Coming up (55β79) and For your information.
Crunch Radar spreads each pending taskβs estimated effort (PPT 3 days, assignment 2, application 1, exam 4β¦)
across the days before its deadline. Days with a load β₯ 2 are crunch days, and each task gets a Smart Start date.
π‘οΈ Rumor Shield, the innovation
WhatsApp groups donβt only lose information; they spread misinformation. Rumor Shield (agent/trust_engine.py)
gives every claim a verdict with evidence.
flowchart LR
M[Message] --> A{Sender authority}
A -->|Prof, HOD, Coordinator, Mentor<br/>or marked official| O[Official Β· 88]
A -->|CR, team lead| S[Semi-official Β· 68]
A -->|Anyone else| P[Member Β· 50]
O & S & P --> H{Hedge language?<br/>'I heard', 'someone said',<br/>'apparently', 'is it true'}
H -->|yes| R[β25 to β45 Β· rumour]
H -->|no| N[score kept]
R & N --> X{Cross-check against official<br/>messages in ALL groups}
X -->|official denial or different date| C[β Contradicted Β· β€12]
X -->|official says the same| V[β
Verified Β· β₯82]
X -->|no official source| U[β οΈ Unverified]
- Signals: sender authority, hedge phrases, forwarded markers, cross-group corroboration and explicit denials (βno changeβ, βas scheduledβ, βignore rumoursβ).
- βPlease ignore rumoursβ from a professor is recognised as a denial, not hearsay.
- Rumours are kept out of Todayβs Brief, can never change an event, and the chatbot and Ask Campus AI warn about them.
Example from the demo data:
Aditya (CSE Final Year): βGuys I heard OS mid-sem is postponed to next week?? not sure π β
β β Contradicted (12/100), evidence: Prof. Sharma: βThere is no change. OS mid-sem will be held as scheduled on 14 Octoberβ¦β
Cross-Group Doubt Solver: a question with no reply from someone else (sharing a topic word) within the next six
messages counts as unanswered. CampusPulse answers it from other groups and documents. For example, βDoes anyone
know where the fest briefing is?β in the class group is answered with the venue change posted in the Fest group.
π² Live WhatsApp integration
Metaβs official WhatsApp Business API canβt read groups a personal number is already in. Its Groups API only covers
groups created by a verified business account. CampusPulse therefore links a number the way WhatsApp Web does,
using a QR code.
sequenceDiagram
actor S as Student
participant UI as Dashboard
participant F as Flask (app.py)
participant B as bridge.js (per user)
participant W as WhatsApp
S->>UI: Click "Show QR code"
UI->>F: POST /api/whatsapp/connect
F->>B: spawn node bridge.js (user's folder + session id)
B->>W: open WhatsApp Web session
B-->>F: status.json = qr, qr.png
UI->>F: poll /api/whatsapp/status (every 3 s)
S->>W: Scan QR on phone (Linked devices)
B-->>F: status = ready, profile.jpg, groups.json
S->>UI: Tick groups β Save
UI->>F: PUT /api/whatsapp/groups
B->>W: fetch recent history (β€300 / group)
B-->>F: messages/*.jsonl (+ PDFs in media/)
loop every 20 seconds
UI->>F: POST /api/whatsapp/sync
F->>F: import new lines β run pipeline
end
| Property | Details |
|---|---|
| One bridge per user |
backend/bridge_manager.py starts bridge.js with that userβs folder (CP_LIVE_DIR) and session (CP_SESSION_ID), so every student links their own number. |
| Read-only | The bridge never sends messages and ignores groups that werenβt ticked. |
| File hand-off |
status.json, groups.json, selected_groups.json, messages/*.jsonl, media/*.pdf, qr.png, profile.jpg, written atomically. |
| Profile | WhatsApp name, masked number, βaboutβ and profile photo are shown on the Profile page. |
| Control | Disconnect (keeps the session) or Unlink (logs out) from the dashboard. |
| Simulator |
scripts/simulate_bridge.py fakes the whole flow (QR, connected profile, groups, streamed messages including a change and a rumour) for demos without a phone. |
β οΈ Automating WhatsApp Web is unofficial and against WhatsAppβs Terms of Service, so the number can be
restricted. For demos, use a spare number that is a member of the groups.
π¬ Ask Campus AI (RAG) and the Pulse chatbot
Retrieval-augmented answers (rag/)
flowchart LR
Q[Question] --> E[Expand with campus synonyms<br/>due β deadline, submitβ¦<br/>where β venue, room, hallβ¦]
E --> S[BM25 over messages + PDF pages]
S --> F[Filter: β₯50% of the asked words,<br/>no questions/chatter, one hit per cluster]
F --> V[Validate: current event values,<br/>conflicts, rumour verdicts]
V --> A[Answer + citations]
- BM25 (k1 = 1.4, b = 0.75). Synonyms count at 0.45 weight. Verified sources Γ1.25, contradicted Γ0.6, plus a gentle recency boost.
- Uses the current event values from the change engine (βnow Wed 5 PM, Main Auditorium, changed from Tue 4 PM, Room 204β).
- Surfaces conflicts and warns when a matching message is a busted rumour.
- Citations come from stored data (group, sender, time, PDF page), never from generated text.
- With an LLM key, a model writes the answer from the numbered evidence only. Message text is wrapped and treated as untrusted data (prompt-injection safe).
Pulse chatbot (backend/chatbot.py), rule-based with no API key
-
Normalise slang:
tmrw β tomorrow,plcmnt β placement,assgn β assignment. - Extract entities: time window (today, tomorrow, this week, next week, a weekday, a date), category and group name.
- Detect intent with ordered regular-expression rules.
- Answer from the studentβs own data, or fall back to the RAG engine with sources.
| Intent | Try saying |
|---|---|
| Deadlines / schedule | βwhatβs due tmrw?β, βplacement deadlinesβ, βwhatβs on Wednesdayβ |
| Changes / conflicts | βany changes?β, βany conflictsβ |
| Rumours | βany rumours?β, βis the fest cancelled?β |
| Tasks | βmy tasksβ, βmark SIH PPT doneβ (actually ticks it off) |
| Planning | βwhen should I start?β, βam I free tomorrow?β |
| Brief | βsummarise todayβ, βwhat did I missβ |
| Account | βis WhatsApp connectedβ, βwho am Iβ, βmy groupsβ |
| Anything else | βwhere is the fest briefing?β β search with sources |
ποΈ Databases
CampusPulse uses SQLite: one shared accounts database plus one database per user. The schema maps directly to
PostgreSQL for a production deployment.
data/
βββ auth.db β accounts only (no messages)
βββ .secret_key β session signing key (auto-generated)
βββ users/
βββ <user_id>/
βββ campuspulse.db β that student's messages, analyses, events, tasks
βββ uploads/ β PDFs they uploaded
βββ live/ β their WhatsApp bridge files
auth.db
| Table | Columns | Purpose |
|---|---|---|
accounts |
id, name, email (unique, case-insensitive), password_hash, created_at, last_login
|
Login identities. Passwords are stored only as salted hashes. |
Per-user campuspulse.db
erDiagram
users ||--o{ groups : owns
groups ||--o{ messages : contains
messages ||--|| message_analyses : "analysed as"
events ||--o{ event_sources : "evidenced by"
messages ||--o{ event_sources : "supports"
events ||--o{ change_logs : "history"
events ||--o{ tasks : "drives"
messages ||--o{ tasks : "source"
groups ||--o{ documents : "shared in"
documents ||--o{ document_chunks : "split into"
users {
int id PK
text name
text profile_json
}
groups {
int id PK
int user_id FK
text name
text category
text official_senders
}
messages {
int id PK
int group_id FK
text timestamp
text sender
text text
text message_type
text links_json
text fingerprint UK
}
message_analyses {
int message_id PK
text category
text type
text summary
text deadline
text location
int is_noise
real confidence
int cluster_id
text relevance
text trust_label
int trust_score
real priority
}
events {
int id PK
text title
text kind
text original_at
text current_at
text original_location
text current_location
text status
}
event_sources {
int event_id PK
int message_id PK
text relation_type
}
change_logs {
int id PK
int event_id FK
text kind
text old_values
text new_values
int source_message_id FK
}
tasks {
int id PK
int event_id FK
int source_message_id FK
text title
text deadline
text status
}
documents {
int id PK
int group_id FK
text filename
text summary
}
document_chunks {
int id PK
int document_id FK
int page_number
text content
}
| Table | Purpose |
|---|---|
users |
The student profile (name, branch, year, batch, interests, skills, teams, pinned demo date) |
groups |
Each WhatsApp group, its category and official senders |
messages |
Raw messages: the source of truth. Never modified by AI. |
message_analyses |
AI output per message: category, type, summary, deadline, venue, noise flag, cluster, relevance, trust verdict, priority |
events |
Deadlines and events with original and current values and a status (active, changed, conflict, cancelled) |
event_sources |
Evidence linking events to messages (origin, duplicate, corroborates, updates, conflicts) |
change_logs |
Audit trail of every change and conflict (old values β new values) |
tasks |
Action items. Status (pending / done) survives pipeline re-runs. |
documents, document_chunks
|
Imported PDFs and page-referenced searchable chunks |
llm_cache |
Cached, validated LLM responses (only used when a key is configured) |
π Authentication and security
| Area | Implementation |
|---|---|
| Passwords | Salted scrypt / PBKDF2 hashes (werkzeug.security); minimum 8 characters with a letter and a number |
| Sessions | Signed cookie: HttpOnly, SameSite=Lax, 7-day lifetime, Secure when COOKIE_SECURE=1; session id regenerated at login |
| CSRF | Every state-changing API call requires a custom X-Requested-With: CampusPulse header |
| Brute force | 5 failed logins per email and IP β 10-minute lockout; the error never reveals which field was wrong |
| Isolation | Separate database, folders and WhatsApp session per account; requests are serialised per user |
| Input safety | Upload size and type limits, secure_filename, HTML escaping in the frontend, WhatsApp group ids checked against the userβs own list |
| Headers |
X-Content-Type-Options: nosniff, X-Frame-Options: DENY, Referrer-Policy: same-origin
|
| Privacy | Phone-number masking, data stays on the machine, delete-all-data and delete-account options |
| Prompt injection | Message text is treated as data; instructions inside messages are ignored |
π REST API
All routes return JSON. Routes other than the auth routes require a logged-in session.
| Method | Route | Description |
|---|---|---|
POST |
/api/auth/register |
Create an account and log in |
POST |
/api/auth/login Β· /api/auth/logout
|
Log in / out |
GET |
/api/auth/me |
Current user, profile, WhatsApp state |
POST |
/api/auth/password |
Change password |
DELETE |
/api/auth/account |
Delete account and all data |
GET PUT
|
/api/profile |
Read / update the academic profile (re-ranks the feed) |
GET |
/api/dashboard |
Todayβs Brief: KPIs, ranked cards, filtered items |
GET |
/api/changes |
Changes and conflicts with both source messages |
GET |
/api/rumors |
Rumour verdicts, evidence and solved doubts |
GET |
/api/deadlines |
Upcoming events, Crunch Radar, Smart Start plan |
GET |
/api/calendar.ics |
Calendar export |
GET Β· PATCH
|
/api/tasks Β· /api/tasks/<id>
|
List / tick tasks |
POST |
/api/ask |
Ask Campus AI (RAG) |
POST |
/api/chat |
Pulse chatbot |
GET |
/api/groups Β· /api/messages Β· /api/resources
|
Groups, filtered messages, PDFs and links |
DELETE |
/api/groups/<id> Β· /api/data
|
Delete a group / all imported data |
POST |
/api/import/chat Β· /api/import/pdf Β· /api/import/demo
|
Upload exports, a PDF, or load demo data |
POST |
/api/reprocess |
Re-run the pipeline |
POST |
/api/whatsapp/connect |
Start the bridge ({"simulate": true} for the simulator) |
GET |
/api/whatsapp/status Β· /qr Β· /avatar
|
Connection state, QR image, profile photo |
PUT |
/api/whatsapp/groups |
Choose groups to read |
POST |
/api/whatsapp/sync Β· /disconnect
|
Pull new messages / disconnect or unlink |
π Folder structure
CampusPulse-AI/
β
βββ app.py # Flask backend: auth + REST API, serves the web frontend
βββ config.py # Settings loaded from .env (paths, LLM, weights, defaults)
βββ streamlit_app.py # Earlier single-user Streamlit dashboard (optional)
βββ requirements.txt
βββ .env.example # Copy to .env (all values optional)
βββ .gitignore
β
βββ web/ # ββ Frontend (HTML Β· CSS Β· JavaScript) ββ
β βββ index.html # Login / create account
β βββ app.html # Dashboard shell: sidebar, header, chat widget, icons
β βββ css/style.css # Two-tone design system, light + dark themes, responsive
β βββ js/
β βββ api.js # fetch wrapper (CSRF header, errors) + HTML escaping
β βββ auth.js # Login / sign-up form, theme toggle
β βββ app.js # SPA router and every page (Today, Changes, Rumors, β¦)
β βββ chatbot.js # Pulse chat widget
β
βββ backend/ # ββ Web backend services ββ
β βββ auth.py # Accounts, password hashing, login throttling
β βββ userspace.py # Per-user database, folders, "today" for demos
β βββ bridge_manager.py # Starts/stops one WhatsApp bridge per user
β βββ chatbot.py # Rule-based chatbot: intents + entity extraction
β
βββ agent/ # ββ The AI pipeline ββ
β βββ orchestrator.py # Runs every stage in order
β βββ classifier.py # Noise filter, category, message type
β βββ extractor.py # Dates, times, venues, links, titles, task names
β βββ trust_engine.py # Rumor Shield + unanswered-question detection
β βββ deduplicator.py # Cross-group duplicate clusters
β βββ change_detector.py # What Changed? engine: events, diffs, conflicts
β βββ personalizer.py # Is this for me? (year, batch, branch, team)
β βββ planner.py # Priority formula, Today's Brief, Crunch Radar
β βββ textutils.py # Tokenising, topic signatures, keyword lists
β βββ llm.py # Optional LLM (Anthropic / OpenAI-compatible)
β
βββ ingestion/ # ββ Getting data in ββ
β βββ whatsapp_parser.py # Android + iOS chat export parser
β βββ normalizer.py # Normalised records, phone masking, fingerprints
β βββ upload.py # Upload validation + import
β βββ pdf_parser.py # PDF text, chunks and key points with page numbers
β βββ live_sync.py # Imports messages streamed by the WhatsApp bridge
β
βββ rag/ # ββ Ask Campus AI ββ
β βββ retrieval.py # BM25 search with campus synonyms
β βββ answer.py # Grounded answers + Cross-Group Doubt Solver
β βββ citations.py # Source labels from stored data
β
βββ database/ # ββ Storage ββ
β βββ models.py # SQL schema
β βββ schemas.py # Pydantic models (validated contracts)
β βββ connection.py # SQLite connection + initialisation
β βββ repository.py # All database reads and writes
β
βββ whatsapp_bridge/ # ββ Live WhatsApp (Node.js) ββ
β βββ bridge.js # QR login, group list, history, live messages, profile
β βββ package.json
β
βββ utils/calendar_export.py # .ics calendar generation
βββ api/main.py # Alternative FastAPI service (optional)
βββ frontend/ # Pages for the Streamlit version (optional)
β
βββ scripts/
β βββ seed_demo.py # Load demo groups + PDF from the command line
β βββ simulate_bridge.py # Fake WhatsApp bridge for demos
β βββ make_sample_pdf.py # Generates the sample SIH guidelines PDF
β
βββ tests/ # 45 tests (pytest)
β βββ test_parser.py # Export formats, multi-line, masking, duplicates
β βββ test_extraction.py # Dates, venues, noise, categories, personalisation
β βββ test_changes.py # Changes, conflicts, clusters, rumours, idempotency
β βββ test_retrieval.py # Answers, PDF citations, doubts, prompt injection
β βββ test_trust.py # Sender authority and hedge scoring
β βββ test_live_sync.py # WhatsApp bridge import
β βββ test_web_api.py # Auth, CSRF, hashing, user isolation
β βββ test_chatbot.py # Chatbot intents and entities
β
βββ data/
β βββ sample_chats/ # 4 synthetic group exports (demo)
β βββ sample_docs/ # Synthetic SIH guidelines PDF
β βββ uploads/
β βββ users/ # Created at runtime, one folder per account (git-ignored)
β
βββ docs/screenshots/ # Images used in this README
π Getting started
Prerequisites
- Python 3.9+
- Node.js 18+ (only for linking a real WhatsApp number)
1. Clone and install
git clone https://github.com/<your-username>/CampusPulse-AI.git
cd CampusPulse-AI
python -m venv .venv
.venv\Scripts\activate # Windows
# source .venv/bin/activate # macOS / Linux
pip install -r requirements.txt
2. Run
python app.py
Open http://127.0.0.1:5000, create an account, and click Load demo data.
3. (Optional) Link a real WhatsApp number
cd whatsapp_bridge
npm install # one time; also downloads a headless Chrome
cd ..
python app.py
In the app go to WhatsApp β Show QR code, then on your phone open Settings β Linked devices β Link a device
and scan the code. Tick the groups to read and click Save groups.
No phone? Click Try a simulated connection.
4. (Optional) Configuration
Copy .env.example to .env. Everything is optional:
| Variable | Purpose |
|---|---|
LLM_PROVIDER, ANTHROPIC_API_KEY / OPENAI_API_KEY, LLM_MODEL, OPENAI_BASE_URL
|
Optional LLM refinement |
FLASK_SECRET_KEY |
Session signing key (auto-generated if empty) |
COOKIE_SECURE=1 |
Use when serving over HTTPS |
WHATSAPP_DATE_ORDER |
DMY (India/UK, default) or MDY (US) exports |
MAX_UPLOAD_MB |
Upload size limit (default 10) |
PORT, HOST
|
Server address (default 127.0.0.1:5000) |
Demo date: the sample chats are dated 5β10 Oct 2026. Loading the demo pins βtodayβ to 10 Oct 2026 for that
account so the deadlines are upcoming. Change or remove it under Profile β Pin βtodayβ to a fixed date.
π¬ Two-minute demo script
- Load demo data: 47 messages from 4 groups, about 32% noise filtered. The SIH PPT deadline is on top, highlighted tomorrow.
- Infosys internship: one card βalso in CSE Final Yearβ, showing the extended deadline.
- What changed: fest briefing Tue 4 PM, Room 204 β Wed 5 PM, Main Auditorium; the DBMS deadline conflict is shown, not auto-resolved.
- Rumor Shield: the mid-sem βpostponedβ rumour is Contradicted by Prof. Sharma; an unanswered question is solved from another group.
- Pulse chatbot: βwhatβs due this week?β, βany rumours?β, βmark sih ppt doneβ.
- Profile: switch to year 3 / 2028 batch, and the 3rd-year Amazon drive moves into the feed.
- WhatsApp: Try a simulated connection, tick the group, and watch new messages, a change and a busted rumour arrive live.
- Dark mode: the sun/moon button in the header.
π§ͺ Testing and evaluation
pytest -q
45 tests cover the evaluation cases from the design:
| Test case | Expected result |
|---|---|
| βok, thanksβ | Marked as noise, not in the brief |
| Same internship in two groups | One cluster, both sources kept |
| βSunday 11:59 PMβ in a Thursday message | Resolved to that Sunday 23:59 |
| Venue changes | Old and new values linked in the change history |
| Two deadlines disagree | Conflict shown; the newer message does not silently win |
| Hearsay βI heard β¦ postponedβ | Never changes the event; marked Contradicted by the official denial |
| SIH team-size question | Answer cites PDF page 2 |
| Announcement for another year | Labelled not for you, with the reason |
| Duplicate export uploaded | No messages imported twice |
| Prompt injection inside a message | Treated as data, not prioritised |
| Second user account | Sees none of the first userβs data |
| Deadline extended | Linked taskβs due date updates; ticked tasks stay ticked |
π οΈ Tech stack
| Layer | Technology |
|---|---|
| Backend | Python, Flask, Werkzeug (password hashing), Pydantic |
| AI pipeline | Rule-based NLP (regex, token signatures, Jaccard, difflib), BM25 retrieval; optional Anthropic / OpenAI-compatible LLM |
| Database | SQLite (PostgreSQL-ready schema) |
| PDFs | pypdf |
| Frontend | Vanilla HTML, CSS (custom properties, light/dark themes) and JavaScript (hash-routed SPA) |
| Live WhatsApp | Node.js, whatsapp-web.js, qrcode |
| Testing | pytest, Flask test client, Playwright (UI checks) |
| Optional | Streamlit dashboard, FastAPI service |
π§ Limitations and roadmap
Current limitations
- Live sync uses an unofficial WhatsApp Web connection (see the warning above).
- Rule-based extraction covers common English / Hinglish patterns; very messy messages benefit from the optional LLM.
- Images and voice notes are recorded as media, not read.
Roadmap
- Official WhatsApp Business Platform bot for institute-created groups
- Poster OCR and voice-note transcription
- Embedding search for paraphrased questions
- Push / email reminders before deadlines
- PostgreSQL and multi-device deployment
- Hindi and regional-language support
Built to give students back the hour a day they spend scrolling through groups.
All demo data is synthetic. Only import chats you are authorised to process.
Built with
AI tools
Prize Categories Entered
- Submitted
Best Use of Gemma 4
- Submitted

Best Open-Source AI Project