Skip to content

Commit c4a312c

Browse files
committed
add: server agents and API, dashboard and mobile app setup
1 parent 7dcd1a3 commit c4a312c

153 files changed

Lines changed: 13832 additions & 5687 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.env.example‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,3 +26,10 @@ MEKO_DATAPACK_ID=
2626
# Optional (Solana devnet)
2727
SOLANA_RPC_URL=https://api.devnet.solana.com
2828
SOLANA_KEYPAIR_PATH=
29+
30+
# Safe Voice, QR stickers, fake-report check
31+
PUBLIC_APP_URL=http://localhost:3000
32+
CAMPUS_SECURITY_PHONE=112
33+
SAFE_REVIEW_DAYS=7
34+
FRAUD_BURST_MIN=5
35+
VERIFIER_USE_LLM=false

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,3 +5,5 @@ node_modules/
55
.next/
66
*.pyc
77
.cache/
8+
media/
9+
.next-test/

‎README.md‎

Lines changed: 54 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,63 @@
11
# ReZolv
22

3-
- `server/` FastAPI + agents (see `architecture.md`, `data_model.md`)
4-
- `app/` Next.js student PWA (port 3000), UI not built yet
5-
- `dashboard/` Next.js staff dashboard (port 3001), UI not built yet
3+
Students report campus problems by voice or text. Agents merge duplicates, find root causes, route issues, and track every promise until the students confirm the fix. Demo campus: Shaheed Sukhdev College of Business Studies, Rohini, Delhi.
64

7-
## Run
5+
| Folder | What | Port |
6+
|---|---|---|
7+
| `server/` | FastAPI, agents, YugabyteDB access | 8000 |
8+
| `dashboard/` | Staff dashboard (Next.js) | 3001 |
9+
| `mobileApp/` | Student app (React Native, Expo) | none, installed on the phone |
10+
| Docker | YugabyteDB | 5433 (SQL), 15433 (web console) |
11+
12+
## Start everything (Windows)
13+
```
14+
powershell -ExecutionPolicy Bypass -File server\start_lan.ps1 # database + API
15+
cd dashboard && npm install && npm run dev # dashboard on http://localhost:3001
16+
```
17+
The server prints its Wi-Fi address (for example `http://192.168.1.236:8000`). Windows blocks incoming connections until the ports are allowed once. Run this in an **administrator** PowerShell:
18+
```
19+
New-NetFirewallRule -DisplayName "ReZolv" -Direction Inbound -Protocol TCP -LocalPort 8000,3001,5433,15433 -Action Allow -Profile Private
20+
```
21+
The dashboard talks to the API through its own `/api` proxy. Set `API_URL` if the API is not on the same machine.
22+
23+
## Logins
24+
| Who | Email | Password |
25+
|---|---|---|
26+
| Student, Student #4F2A | `ananya.s@democampus.edu` | `student123` |
27+
| Student | `rahul.k@democampus.edu` | `student123` |
28+
| Student | `meera.p@democampus.edu` | `student123` |
29+
| Facilities Head, escalation level 1 | `facilities@rezolv.demo` | `staff123` |
30+
| Warden, level 2 | `warden@rezolv.demo` | `staff123` |
31+
| Dean, level 3 | `dean@rezolv.demo` | `staff123` |
32+
33+
A promise starts with the department, moves to the Warden at its deadline, and to the Dean 24 hours later. It also moves up one level when a student answers "Still broken" after the deadline. RZV-209 is with the Dean, RZV-226 with the Warden, and RZV-219 waits for a student: log in as a student, answer "Still broken", then check the Warden's Escalations page.
34+
35+
## Student app (Expo)
36+
```
37+
cd mobileApp
38+
npm install
39+
npx expo start --lan # quick test in Expo Go on the same Wi-Fi
40+
```
41+
Build an installable APK (needs a free Expo account):
842
```
9-
cp .env.example .env # fill in keys (all optional to start)
10-
docker compose up --build # db + server + app + dashboard
11-
docker compose exec server python seed.py --reset
43+
npx eas-cli@latest login
44+
npx eas-cli@latest build -p android --profile preview
1245
```
13-
Server docs: http://localhost:8000/docs · health: http://localhost:8000/health
46+
`eas.json` bakes in the server address `http://192.168.1.236:8000`. If your laptop's address changes, edit `EXPO_PUBLIC_API_URL` there before building, or change the address inside the app (login screen or Profile). The phone and the laptop must be on the same Wi-Fi.
1447

15-
Local dev without Docker: start only `yugabytedb` in compose, then in `server/`
16-
`pip install -r requirements.txt && python -m scripts.migrate && uvicorn main:app --reload`
17-
(set `DATABASE_URL` host to `localhost`), and `npm install && npm run dev` in `app/` and `dashboard/`.
48+
## Database access
49+
YugabyteDB runs in Docker (`docker compose up -d yugabytedb`).
1850

19-
## Connectivity checks (run in `server/`)
20-
- `python -m scripts.check_gemini` lists usable models, tests embed + classify
21-
- `python -m scripts.list_meko_tools` prints Meko tool names and argument schemas
22-
- `python -m scripts.setup_storage` creates the Vultr buckets and CORS
51+
| | |
52+
|---|---|
53+
| Host | `192.168.1.236` (or `localhost` on this machine) |
54+
| Port | `5433` (YSQL, PostgreSQL compatible) |
55+
| Database | `yugabyte` |
56+
| User / password | `yugabyte` / `yugabyte` |
57+
| Connection string | `postgresql://yugabyte:yugabyte@192.168.1.236:5433/yugabyte` |
58+
| Web console | `http://192.168.1.236:15433` |
2359

24-
Demo logins, password `rezolv123`: `student01@campus.demo` ... `student50@campus.demo`,
25-
`dean@`, `warden@`, `it@`, `estates@`, `committee@` `rezolv.demo`.
60+
Use any PostgreSQL client (DBeaver, pgAdmin, `psql`). Useful tables: `issues`, `reports`, `promises`, `issue_events`, `issue_links`, `confirmations`. Student reports store only a pseudonym, never a user id.
2661

27-
Without keys everything still runs: Gemini falls back to keyword classification and mock
28-
embeddings (typed reports only), Meko and Solana calls are skipped.
62+
## More
63+
`server/README.md` has the API, the agents and the measured-numbers rules. `PLAN.md` and `features.md` describe the product.

‎content.md‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
# ReZolv: pitch content
2+
3+
One line: **students report campus problems in their own language, agents merge them and find the real cause, every promise has an owner and a deadline and escalates by itself, and an issue closes only when the students say it is fixed.**
4+
5+
Pilot campus: Shaheed Sukhdev College of Business Studies (SSCBS), Rohini, Delhi.
6+
7+
## 1. How big is the problem
8+
9+
### The scale of the audience
10+
- India's All India Survey on Higher Education 2021-22 registered **1,168 universities, 45,473 colleges and 12,002 stand-alone institutions**.
11+
- Total enrolment was about **4.33 crore students**, up from 4.14 crore a year earlier and 3.42 crore in 2014-15 (about 26.5% growth).
12+
- More than **70% of students are enrolled in colleges**, not universities. These are exactly the institutions with a warden, a mess, a hostel and a single grievance box.
13+
14+
### Grievance channels already exist on paper, and are not trusted or used well
15+
- The UGC (Redress of Grievances of Students) Regulations, 2023, notified on 11 April 2023, require **every higher education institution to set up a Students' Grievance Redressal Committee**, and every university to appoint an **ombudsperson** for appeals.
16+
- Four months after UGC directed universities to appoint an ombudsperson, a Hindustan Times report found **72.7% had not complied**. UGC later set a 31 December 2023 deadline and said it would publish the names of defaulters. One Tribune report counted 159 state-run universities still without one.
17+
- So the legal duty exists, the tooling to meet it is missing, and colleges need a way to show they act.
18+
19+
### Students do report, and the numbers are rising
20+
- UGC's anti-ragging helpline received **582 complaints in 2021-22** and about **858 in 2022-23**, reported as a 47% rise. Another report counts **1,240 complaints between 1 January 2023 and 28 April 2024** (about 16 months).
21+
- A Lok Sabha reply counted **2,790 ragging complaints since 2018**.
22+
- The helpline only forwards a complaint to the concerned authority. After that, the student cannot see whether anything happens.
23+
24+
### The human cost
25+
- The National Crime Records Bureau recorded **13,044 student suicides in 2022, 7.6% of all suicides in India**, after 13,089 in 2021.
26+
- This figure is not caused by grievance handling, and we do not claim it is. We use it to show how much is at stake when students feel unheard, and why a channel that visibly responds matters.
27+
28+
### What the data does not show
29+
There is **no national dataset of everyday campus facility complaints** (water, Wi-Fi, mess, lights). The figures above measure the audience, the legal duty and the most serious cases, not the daily volume. We do not invent that number. Our own pilot is how we measure it: reports per student per month, share merged as duplicates, promises kept, time to fix.
30+
31+
### Why now
32+
- A statutory obligation (UGC 2023 regulations) with low compliance.
33+
- Hindi-English code-mixed speech can now be understood by models such as Gemini, so "report in your own language" works without forms.
34+
- Vector search inside a normal database (YugabyteDB with pgvector) makes duplicate detection cheap to run.
35+
36+
## 2. Novelty
37+
38+
1. **Root causes are measured, not guessed.** A time-lag test in SQL compares real issue timelines against 500 shuffled ones. In our demo data, 6 of 6 Hostel B power cuts were followed by a water outage within 48 hours, against about 15% by chance (p = 0.002). Only a pattern that passes goes to Gemini, which explains it in one sentence. The same pattern then drives forecasts from planned events.
39+
2. **Every "Why?" is checked before it is shown.** Each agent decision cites evidence. A verifier recomputes the numbers from YugabyteDB. Claims it cannot confirm are labelled "unverified", never presented as fact.
40+
3. **Students close issues, staff cannot.** Staff can only say "fixed". It closes when most reporters confirm. If a student says "still broken" after the deadline, the issue reopens and moves up one level (department, Warden, Dean) automatically.
41+
4. **Duplicates merge across languages.** Hindi, English and Hinglish reports of the same problem become one issue, using embeddings of both the original text and its translation. On our 20-report labelled test set: 100% merge precision and recall.
42+
5. **Escalations quote the college's own rules.** The three college PDFs (Code of Conduct, Hostel Bulletin, college knowledge base) sit in Meko's knowledge base. A passage is quoted only when Meko ranks it as relevant.
43+
6. **The router learns from staff corrections**, saved to the database and to Meko memory, and the dashboard shows routing accuracy over time.
44+
7. **Only measured numbers are shown.** Accuracy comes from a labelled test set we built, not from a general claim.
45+
46+
## 3. Features (what works today)
47+
48+
**Student app (Android, React Native)**
49+
- Report by voice or text in Hindi, English or Hinglish, with an optional photo.
50+
- Pin the exact spot on an OpenStreetMap map locked to the campus, and pick the floor.
51+
- Receipt code, and a live note of how many others reported the same thing.
52+
- Campus map of open issues, colored by category, with "Me too".
53+
- My reports with a four-step progress bar (sent, routed, promised, fixed).
54+
- Issue page: promise, lateness, who it is with now, the measured root cause, a timeline, and "Why?".
55+
- Confirm the fix: yes, partly, still broken.
56+
- Campus scorecard of promises kept per department.
57+
58+
**Staff dashboard (Next.js)**
59+
- Three staff levels with their own queues: Facilities Head, Warden, Dean.
60+
- Overview, issues with filters, promises board (overdue, due soon, waiting for students, on track, kept), campus map, scorecard.
61+
- Issue page: set a promise, mark fixed, move to another department, timeline and "Why?" with verified / unverified tags.
62+
- Root causes with the measured numbers, forecasts, and "Fix the cause, close them all".
63+
- Agent activity and a flagged-reports list for suspected coordinated reports.
64+
- Profile with password change.
65+
66+
**Agents (server)**
67+
Intake (transcribe, translate, classify), clusterer, router, root-cause, memory (saves a playbook when an issue is fixed, suggests it for similar issues), promise keeper, fraud check, verifier.
68+
69+
**Built in the server, not on screen in the prototype**
70+
Safe Voice for sensitive complaints (the student chooses how visible they are, a confidential officer, urgent override, anonymous chat), QR stickers on campus objects, and a Solana anchoring module that is switched off. We left these out of the screens on purpose, to keep the prototype simple.
71+
72+
## 4. Technology used
73+
74+
| Technology | What it does here |
75+
|---|---|
76+
| **YugabyteDB** | One database for everything: relational tables (issues, reports, promises), vector search (pgvector with the `ybhnsw` index) to merge duplicates by meaning, and time-series analysis for the root-cause test. A single query also joins places, issues, causes and nearest-meaning issues. |
77+
| **Meko** | Shared memory for the agents: each issue's decisions are stored as a conversation (the "Why?" trail), playbooks and routing corrections go to memory, token use is tracked, and the three college PDFs are the knowledge base that escalations quote. |
78+
| **Gemini** | Speech transcription, translation and classification (`gemini-3.5-flash-lite`), 768-dimension embeddings, one-sentence explanation of a measured cause. Calls are rate limited, cached and budgeted so the shared key never stops the demo. |
79+
| **FastAPI (Python)** | The API and the background agents. |
80+
| **Next.js** | Staff dashboard. |
81+
| **React Native with Expo** | The Android student app. |
82+
| **OpenStreetMap and Leaflet** | The campus map, locked to the college boundary. |
83+
| **Docker** | Runs YugabyteDB. |
84+
| Vultr | Object storage for voice and photos is supported; the demo stores files on the server disk. |
85+
86+
## 5. Impact
87+
88+
Honest framing: these are the outcomes ReZolv is built to move. We have not measured them yet. The pilot measures them.
89+
90+
- **Students:** a report that visibly goes somewhere. A receipt, a named owner, a deadline, and the right to say "still broken".
91+
- **Administration:** thirty-one complaints become one issue with a cause and an owner, instead of thirty-one messages. Wardens and deans see only what has reached their level.
92+
- **Accountability:** a public scorecard of promises kept per department. In our seed data IT Services keeps 92% of its promises, and the Estates departments less. That gap is the conversation the college needs to have.
93+
- **Compliance:** every report, promise, escalation and student confirmation is a time-stamped record. That is the evidence trail a college needs to show it handles grievances under the UGC 2023 regulations.
94+
- **Prevention:** forecasts turn a planned power cut into a warning before students lose water.
95+
96+
Pilot metrics we will report: reports per student per month, share of reports merged as duplicates, median time from report to first promise, share of promises kept, share of issues closed by student confirmation, escalations per month.
97+
98+
## 6. Target customers
99+
100+
1. **Primary: colleges and universities.** Buyer: the Dean of Students or Registrar. Users: students (reporters) and wardens, estates, IT and mess heads (resolvers). Start with a Delhi University college (SSCBS) and expand to other affiliated colleges.
101+
2. **Secondary: institution groups and residential campuses** such as private universities and hostel operators, where facility complaints are daily.
102+
3. **Later: regulators and state education departments** who want a view of grievance handling across many institutions.
103+
104+
The wedge is simple: a college that must run a grievance committee under the UGC regulations and has no tool beyond a paper box.
105+
106+
## 7. Revenue model
107+
108+
Assumptions, not facts. Prices are placeholders to test in the pilot.
109+
110+
- **Pilot (free, one semester):** one college, to measure the metrics in section 5.
111+
- **Institution subscription, per enrolled student per year.** Illustrative: Rs 25 to Rs 40 per student per year. A college of 2,000 students pays Rs 50,000 to Rs 80,000 a year. No fee for students.
112+
- **Compliance add-on:** exportable records of grievances, promises and escalations for the grievance committee and ombudsperson.
113+
- **Group and state licences:** consolidated dashboards across many campuses.
114+
115+
Sizing, as arithmetic on the AISHE counts, with our assumed price: 4.33 crore enrolled students at Rs 30 would be about Rs 1,300 crore a year if every institution adopted. That is a ceiling, not a forecast. A realistic early target is a handful of Delhi University colleges, then a few percent of the 45,473 colleges.
116+
117+
Cost to serve is low: the heavy AI calls happen once per new issue (about two Gemini calls), duplicates and "me too" add none, and repeats reuse saved playbooks.
118+
119+
## 8. Roadmap
120+
121+
Safe Voice screens, QR stickers on water coolers and routers, push notifications, Hindi/Tamil/Odia app language, SSO with the college login, rulebook upload by the college, Vultr object storage and hosting, and optional Solana anchoring of report hashes.
122+
123+
## Sources
124+
- AISHE 2021-22, Ministry of Education: [report PDF](https://education.gov.in/sites/upload_files/mhrd/files/statistics-new/AISHE%20Book_2021-22_4.pdf); coverage: [Free Press Journal](https://www.freepressjournal.in/education/aishe-report-survey-records-433-crore-enrolments-in-higher-education-in-india), [Business Standard](https://business-standard.com/india-news/enrolment-in-higher-education-reached-43-3-million-in-2021-22-report-124012700116_1.html).
125+
- UGC anti-ragging helpline: [Free Press Journal, 2022-23](https://www.freepressjournal.in/education/ugc-data-reveals-rise-in-ragging-cases-across-india-in-202223), [Free Press Journal, 2023-24](https://www.freepressjournal.in/education/fpj-exclusive-45-rise-in-ragging-cases-in-202324-ugc-pledges-safe-learning-environment), [Careers360, since 2018](https://news.careers360.com/over-2700-complaints-of-ragging-in-higher-educational-institutions-received-2018-govt).
126+
- Student suicides, NCRB data as reported in Parliament: [The Week / PTI](https://www.theweek.in/wire-updates/national/2025/07/21/del88-lsq-moe-student-suicides.html).
127+
- UGC Redress of Grievances of Students Regulations 2023: [regulation text](https://thc.nic.in/Central%20Governmental%20Regulations/University%20Grant%20Commission%20(Redressal%20of%20Grievances%20of%20Students)%20Regulations,%202023.pdf), [Careers360 on ombudsperson deadlines](https://news.careers360.com/ugc-asks-universities-appoint-ombudspersons-will-publish-names-of-defaulters-after-deadline), [Tribune](https://www.tribuneindia.com/news/delhi/159-state-run-universities-yet-to-appoint-ombudsperson-university-grants-commission-600945), [Hindustan Times via Magzter](https://www.magzter.com/tr/stories/newspaper/Hindustan-Times/727-VARSITIES-YET-TO-APPOINT-OFFICER-FOR-GRIEVANCE-PANELS).
128+
129+
Figures were taken from news coverage of the official reports. Check the primary documents before quoting a number on stage.

0 commit comments

Comments
 (0)