CityBrain is a smart campus cafeteria MVP that helps students check cafeteria congestion before visiting and helps operators review congestion trends after operation.
The project started as a student cafeteria app, but it has been expanded into a pilot-ready campus operation package with YOLO-based congestion estimation, automatic logging, operating-window control, admin protection, CSV export, pilot reporting, and privacy-aware operation documents.
This repository is organized as a school-facing MVP, not just a UI demo.
CityBrain answers one simple campus problem:
“Can students and cafeteria operators know the cafeteria congestion level before and during lunch time without storing original video?”
The current version supports:
- Student-facing congestion status page
- YOLO / webcam / RTSP-based person-count estimation
- Backend proxy API for congestion status
- Manual and automatic congestion logging
- Operating-window based auto logging
- Admin-only history, CSV export, and pilot report pages
- Privacy-aware CCTV and video-processing documentation
- Pilot evaluation metrics and operation checklist
The strongest point of this project is not only the screen implementation.
It connects implementation, operation, privacy review, and pilot evaluation into one flow.
Most campus apps stop at showing static information.
CityBrain focuses on an operational problem:
- Students want to avoid crowded cafeteria times.
- Cafeteria operators need time-based congestion data.
- Schools need a privacy-aware way to test smart campus services.
- Vendor or POS integration may not be available at the early stage.
CityBrain therefore starts with a realistic path:
Manual input
→ YOLO-based auxiliary measurement
→ Automatic logging
→ Operating-window control
→ Admin-only report
→ CSV export
→ Pilot evaluation
→ Future POS / kiosk integration
Current MVP Capabilities
Area Current Capability
Student page Students can view cafeteria congestion status
Vision module YOLO-based person count from webcam or RTSP source
Backend API FastAPI proxy and congestion status API
History logging Congestion records can be saved and reviewed
Auto logging Server can save congestion statistics automatically
Operating window Auto logging can be limited to selected time ranges
Admin guard Admin pages and control APIs require an admin key
CSV export Congestion history can be exported for review
Pilot report Stored logs are summarized into an operator-facing report
Privacy docs CCTV/video handling considerations are documented
Evaluation docs Pilot metrics and operation checklist are included
School Pilot Positioning
CityBrain should be presented as:
A privacy-minimized cafeteria congestion statistics MVP
that stores person count, congestion level, and timestamp only.
It is not intended to be:
a surveillance system
a face recognition system
a student tracking system
an attendance-checking system
a replacement for formal CCTV/privacy approval
Before any real campus deployment, the school should review camera purpose, notice signage, camera angle, admin access, server operation responsibility, and privacy policy.
## Key Technologies
`FastAPI` `SQLite` `Kotlin` `Jetpack Compose`
`Android Client Structure` `Admin Web` `Student Web` `Smart Campus`
`Operational Dashboard` `Service MVP` `YOLO` `Computer Vision`
---
## Architecture
```text
[Student Web]
menu view / congestion status / student participation
↓
[FastAPI Backend]
menu / congestion / feedback / notice / admin APIs
↓
[SQLite Database]
MVP-level local data storage
↑
[Admin Web]
operation monitoring / menu management / feedback review
↑
[Jarvis Assistant]
local assistant-style query interface for campus dining information
[Webcam / RTSP Camera]
↓
[YOLO Person Detection Module]
↓
[People Count / Congestion Level]
↓
[CityBrain Backend Proxy API]
↓
[Student Vision Status Page]
↓
[Admin Vision Report / History Log / CSV Export]
Campus dining services often have information gaps between students and operators.
Students want to know:
- what menu is available
- how crowded the cafeteria is
- how many meals are likely left
- how long the expected wait may be
- whether it is worth visiting now
Operators need visibility into:
- student demand
- menu response
- feedback patterns
- congestion status
- operational bottlenecks
CityBrain explores how a smart campus service can connect both sides through a lightweight MVP architecture.
- Student cafeteria home screen
- Real-time remaining meal count
- Congestion status display
- Expected waiting time display
- Today menu and weekly menu preview
- Student feedback and survey flow
- Admin operation dashboard
- Menu and quantity management
- Admin-side quick operation actions
- Jarvis-style campus assistant screen
- Status page and API documentation
- Student and admin web interfaces
- YOLO-based congestion estimation demo
- Student AI congestion status page
- Admin AI congestion report page
- Vision congestion history logging
- CSV export for recorded congestion data
This project is not just a static UI prototype.
It includes:
- FastAPI backend
- SQLite persistence
- admin/student interface separation
- local demo environment configuration
- API documentation through FastAPI Swagger UI
- service status page
- production gap analysis
- documentation for security and deployment limitations
- Android client structure and Jetpack Compose prototype direction
- YOLO-based person detection module
- backend proxy API for vision data
- fallback handling when the vision module is unavailable
- vision history logging and CSV export
This repository includes documentation for areas that must be improved before real deployment:
| Document | Purpose |
|---|---|
docs/DEMO_ACCOUNT_POLICY.md |
Demo account and security boundary |
docs/PRODUCTION_GAP.md |
Authentication, privacy, reliability, and deployment gaps |
docs/CAMPUS_PILOT_PROPOSAL.md |
Campus pilot proposal |
docs/VISION_PRIVACY_POLICY_DRAFT.md |
Vision privacy and video handling draft |
docs/OPERATOR_RUNBOOK_VISION.md |
Vision module operator runbook |
Before production deployment, the following areas would require additional work:
- student identity verification
- role-based access control
- HTTPS and secure session handling
- privacy policy and consent flow
- production database migration
- monitoring and backup strategy
- accessibility and responsive QA
- Android release signing
- operational incident response process
- CCTV access permission review
- camera position and signage review
- school-level privacy and video processing review
From the backend directory:
cd backend
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reloadStudent web:
http://127.0.0.1:8000/
Admin web:
http://127.0.0.1:8000/admin/login
Jarvis assistant:
http://127.0.0.1:8000/jarvis
Status page:
http://127.0.0.1:8000/status
API docs:
http://127.0.0.1:8000/docs
CityBrain vision features require two local servers.
cd vision/congestion_demo
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python app.pyYOLO vision API:
http://127.0.0.1:8081/api/congestion/latest
cd backend
source ../.venv/bin/activate
uvicorn app.main:app --host 127.0.0.1 --port 8080 --reloadCityBrain vision API:
http://127.0.0.1:8080/api/vision/congestion
Student vision page:
http://127.0.0.1:8080/student/vision-status
Admin vision report:
http://127.0.0.1:8080/admin/vision-report
Admin vision history:
http://127.0.0.1:8080/admin/vision-history
CSV export:
http://127.0.0.1:8080/api/vision/history/export.csv
Prototype concept board for portfolio/demo purposes.
This is not an official university service screen.
1. Admin updates meal quantity / congestion status
2. Backend stores current operation state
3. Student web displays updated cafeteria status
4. Students can check menu, remaining quantity, wait time, and notices
5. Student feedback can support future operation decisions
1. Webcam or RTSP camera provides a live frame
2. YOLO module detects people
3. Vision module calculates people count and congestion level
4. CityBrain backend reads the result through /api/vision/congestion
5. Student page displays current AI congestion status
6. Admin report displays operation guidance
7. Admin history page saves logs
8. CSV export allows pilot data review
CityBrain V8.3 adds a YOLO-based congestion estimation demo as an alternative data collection path when kiosk/OBU integration is unavailable.
This module is located under:
vision/congestion_demo
The goal is to estimate cafeteria congestion from webcam or RTSP camera streams by detecting people and converting the result into congestion statistics.
Webcam / RTSP Camera
→ YOLO Person Detection
→ People Count / Queue Length
→ Congestion Level
→ CityBrain Student Screen
cd vision/congestion_demo
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python app.pyOpen:
http://127.0.0.1:8081
API:
http://127.0.0.1:8081/api/congestion/latest
- This is an MVP/demo module.
- It supports webcam-based testing and can be extended to RTSP CCTV/IP camera streams.
- It does not aim to identify individuals or store original video.
- The goal is to calculate congestion statistics based on people count or queue length.
- Official deployment would require CCTV policy, privacy, and access permission review.
CityBrain의 학교 파일럿 검토를 위한 문서는 아래에 정리했다.
CityBrain 심사와 시연 때 보여줄 증거 자료는 아래 폴더에 정리했다.
- evidence/README.md
- evidence/screenshots
- evidence/demo-flow
- evidence/code-structure
- evidence/runbook
- evidence/interview-notes
CityBrain 시연 및 실행 절차는 아래 문서에 정리했다.
- CITYBRAIN_RUNBOOK.md
- CITYBRAIN_CODE_FLOW.md
- code-reading-log.md
- docs/OPERATOR_RUNBOOK_VISION.md
- CCTV Privacy and Congestion Research
This MVP does not claim:
- production-grade university deployment
- official university service status
- real student identity verification
- complete privacy-policy compliance
- high-availability operation
- store-ready Android release
- full accessibility certification
- real cafeteria system integration
- fully validated CCTV deployment
- legal approval for real campus video operation
- production-grade AI accuracy
This project is a smart campus MVP focused on service flow, interface structure, field research, and operational feasibility.
- Add student ID verification
- Add role-based access control
- Add privacy policy and consent flow
- Add production database migration
- Add monitoring and backup strategy
- Add Android release signing
- Add accessibility and responsive QA
- Add real cafeteria operation data integration
- Add kiosk/POS integration scenario
- Add historical demand analytics
- Add admin audit logging
- Add scheduled automatic vision logging
- Add CSV-based weekly operation report
- Add real pilot feedback form
- Add camera-position accuracy testing
CityBrain is a smart campus MVP focused on campus dining operations.
I built it to explore how student-facing information and admin-side operational visibility can be connected through a FastAPI backend, SQLite database, student web, admin dashboard, local assistant-style interface, and YOLO-based congestion estimation module.
Added YOLO-based congestion estimation demo.
Connected YOLO vision module to CityBrain backend through /api/vision/congestion.
Added student-facing AI congestion status page.
Added admin-facing AI congestion operation report.
Added vision congestion history logging.
Added CSV export for recorded congestion data.
Added campus pilot proposal, privacy/video handling draft, and operator runbook.
Packaged the project as a campus pilot-ready MVP.
CityBrain v9.4 adds automatic vision congestion logging.
Admin auto logging page:
http://127.0.0.1:8080/admin/vision-auto-logging
Auto logging APIs:
GET /api/vision/auto-logging/status
POST /api/vision/auto-logging/start?interval_seconds=60
POST /api/vision/auto-logging/stop
POST /api/vision/auto-logging/run-once
CityBrain v9.5 adds operating-window control for automatic vision congestion logging.
The auto logging feature can now save congestion records only during a configured time window, such as the lunch peak period.
Default operating window:
11:30 ~ 13:30
Admin page:
http://127.0.0.1:8080/admin/vision-auto-logging
Updated API example:
POST /api/vision/auto-logging/start?interval_seconds=60&start_time=11:30&end_time=13:30&respect_operating_window=true
Status API includes:
within_operating_window
operating_start
operating_end
skip_count
last_skipped_at
This makes the vision logging module more suitable for a limited campus cafeteria pilot because the system does not need to collect data outside the intended operation time.
CityBrain v9.6 adds a simple admin key guard for local MVP admin pages and control APIs.
Student-facing pages remain open, but admin pages, CSV export, and auto-logging control APIs require an admin key.
Default local admin key:
<your-admin-key>
Admin pages:
http://127.0.0.1:8080/admin/vision-report?admin_key=<your-admin-key>
http://127.0.0.1:8080/admin/vision-history?admin_key=<your-admin-key>
http://127.0.0.1:8080/admin/vision-auto-logging?admin_key=<your-admin-key>
API header example:
X-Admin-Key: <your-admin-key>
Curl example:
curl -H "X-Admin-Key: <your-admin-key>" http://127.0.0.1:8080/api/vision/auto-logging/status
Environment variable:
CITYBRAIN_ADMIN_KEY=<your-admin-key>
This is not a full production login system. It is a lightweight local MVP guard to prevent unauthenticated access to administrator functions during pilot testing.
CityBrain v9.7 adds an admin-only pilot report page based on stored vision congestion logs.
Admin report page:
http://127.0.0.1:8080/admin/vision-pilot-report?admin_key=<your-admin-key>
Report API:
GET /api/vision/pilot-report?limit=1000
The report summarizes:
- total congestion log count
- average detected people
- maximum detected people
- minimum detected people
- congestion-level counts
- hourly average people count
- recent 10 logs
- school-facing summary text
This helps convert raw congestion logs into a pilot operation summary that can be reviewed by school staff or cafeteria operators.
CityBrain v9.8 adds pilot operation and evaluation documents.
Documents:
docs/PILOT_EVALUATION_METRICS.md
docs/PILOT_OPERATION_CHECKLIST.md
These documents define how to operate a limited cafeteria pilot, what metrics to evaluate, and what privacy/operation checks must be completed before real campus use.
CityBrain v9.9 separates local demo settings from pilot-ready configuration.
Environment variables:
CITYBRAIN_ADMIN_KEY=<your-admin-key>
VISION_MODULE_URL=http://127.0.0.1:8081/api/congestion/latest
CITYBRAIN_OPERATING_START=11:30
CITYBRAIN_OPERATING_END=13:30
Protected admin pages require an admin key.
Example:
http://127.0.0.1:8080/admin/vision-pilot-report?admin_key=<your-admin-key>
API example:
curl -H "X-Admin-Key: <your-admin-key>" http://127.0.0.1:8080/api/vision/pilot-report
This version keeps the local MVP simple while making configuration boundaries clearer for a future school pilot.