College Ess
About the project
๐ College Ess
Everything a student juggles โ in one place.
Your wardrobe, your routine, your deadlines, your clubs, your exams.
Synced everywhere. Works offline. Installs like an app.
Architecture ยท Modules ยท Stack ยท Roadmap ยท Developer docs
๐ก The problem
A studentโs life is scattered across eight apps that donโt talk to each other.
Your exam timetable is a PDF. Your clubโs meeting is in a WhatsApp group. Your laundry
is a mental note you forgot. The fest you wanted to attend clashed with a lab you didnโt
check. Nothing knows about anything else.
College Ess is one app where all of it lives together โ and where each piece actually
knows about the others.
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ 9:41 โโโ โฎโฎ โ
โ โ
โ Good morning, Harshit โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ
โ โธ TODAY ยท Class day โ
โ โ
โ 08:30 โ Physics โ LH3 โ
โ 10:15 โ DSA Lab โ CL2 โ
โ 14:00 โ ๐ญ Drama club meet โ
โ โ
โ โธ WEARING โ
โ โโโโโโ โโโโโโ โ
โ โ ๐ โ โ ๐ โ 2 wears left โ
โ โโโโโโ โโโโโโ โ
โ โ
โ โธ UP NEXT โ
โ โ Midsem in 6 days โ
โ โ Buy notebooks โ
โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ ๐ ๐ ๐ ๐
โ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โจ Twelve modules, one app
๐งฉ One idea holds the whole thing together
Six of these modules are structurally identical. A todo deadline, an exam, an event,
a holiday, a class block, a club meeting โ they differ by label, not by shape.
So they arenโt six apps. Theyโre six views over one table.
flowchart TD
L["๐ Loop"]:::mod
R["๐ Rhythm"]:::mod
C["๐ Crunch"]:::mod
B["๐ด Breather"]:::mod
K["๐ญ Circles"]:::mod
Z["๐ช Buzz"]:::mod
L -->|kind=todo| I
R -->|kind=class_block| I
C -->|kind=exam| I
B -->|kind=holiday| I
K -->|kind=club_meeting| I
Z -->|kind=event| I
I[("๐๏ธ item<br/><i>one unified record</i>")]:::core
I --> D["๐ *_detail tables<br/><i>kind-specific fields</i>"]:::sub
classDef mod fill:#1e293b,stroke:#475569,color:#e2e8f0
classDef core fill:#2563eb,stroke:#1d4ed8,color:#ffffff
classDef sub fill:#334155,stroke:#475569,color:#e2e8f0
Why it matters: reclassifying a todo as an exam is a single field update โ not a
migration across two tables. And โwhatโs happening next week?โ is one query across
every module, for free.
๐ Modules that actually talk to each other
Cross-module connections are rows in an edge table, not schema changes. Adding a new
one costs nothing.
flowchart LR
O["๐ Outfit"]:::a -->|wears_at| E["๐ช Fest"]:::b
T["๐ Buy fabric"]:::a -->|prepares_for| E
S["๐ Midsem"]:::b -->|blocks| RT["๐ Routine"]:::c
H["๐ด Long weekend"]:::c -->|derived_from| RT
TK["๐ Design poster"]:::a -->|belongs_to| CL["๐ญ Drama Club"]:::b
classDef a fill:#0f766e,stroke:#14b8a6,color:#fff
classDef b fill:#7c3aed,stroke:#a78bfa,color:#fff
classDef c fill:#b45309,stroke:#f59e0b,color:#fff
Pick an outfit for a fest โ it appears on your timeline that morning.
Exams approach โ your routine switches to study mode.
A long weekend appears โ tasks you saved for free time surface.
๐ก Offline is not an afterthought
Campus wifi is bad. The app is built for that.
flowchart LR
U["๐ฑ You"] -->|write| OB["๐ฅ Outbox<br/><i>IndexedDB</i>"]
U -->|read| QC["โก Local cache<br/><i>instant</i>"]
OB -.->|"on reconnect"| API["โ๏ธ API"]
API --> DB[("๐ Postgres")]
DB -.->|"changes since"| QC
classDef x fill:#1e293b,stroke:#475569,color:#e2e8f0
class U,OB,QC,API,DB x
Write a todo in a dead zone. It saves instantly, queues, and lands when youโre back.
The guide is cached in full โ because you need help most when the network is worst.
๐๏ธ Built to run on nothing
Every piece was chosen to fit inside a free tier โ $0 to roughly 800 users.
flowchart TB
subgraph edge [" "]
direction LR
P["๐ฑ PWA<br/><i>installable</i>"]:::u
end
P -->|HTTPS| V["โฒ Vercel<br/><i>Next.js + API</i>"]:::v
P -->|"presigned upload"| B2["๐ชฃ Backblaze B2<br/><i>10GB free ยท no card</i>"]:::bz
V --> NE[("๐ Neon Postgres<br/><i>no idle pause</i>")]:::db
CW["โฐ CF Worker<br/><i>cron ยท every minute</i>"]:::cf -->|tick| V
V -->|"Web Push"| P
classDef u fill:#2563eb,stroke:#1d4ed8,color:#fff
classDef v fill:#000000,stroke:#333,color:#fff
classDef cf fill:#F38020,stroke:#c2410c,color:#fff
classDef bz fill:#E21E29,stroke:#b91c1c,color:#fff
classDef db fill:#166534,stroke:#22c55e,color:#fff
| Choice | Why this one |
|---|---|
| ๐ชฃ Backblaze B2 for files | 10 GB free with no card needed; downloads free up to 3ร whatโs stored, so images are cached on the device |
| โฐ Cloudflare cron | Vercelโs free tier caps cron at once per day; reminders need minutes |
| ๐ Neon | Free Postgres that doesnโt pause on idle |
| ๐ Better Auth | Self-hosted, TOTP built in, unlimited users, $0 forever |
| ๐ Web Push | Native, no Firebase, no third party |
๐ Privacy, by design
|
๐ซ Your data stays in your college |
๐ค AI never sees a training tier |
|
๐ฌ Chat stays encrypted |
๐ You choose what leaves your device |
๐ Try it locally
pnpm install
cp .env.example apps/web/.env.local
# in apps/web/.env.local, set DATABASE_URL=pglite://memory
pnpm dev
Open http://localhost:3000. No database setup needed โ pglite://memory runs an
in-process Postgres. Every other value in the file must be present too: the server
refuses to start without them, and says which are missing.
๐ ๏ธ Building on this? README-dev.md has the architecture in
depth, the conventions that are load-bearing, an honest assessment of the current
state, and what to be careful about. Read it before your first commit.
๐ค Contributing
Foundation work is active, so the shape of things is still moving. A few conventions are
load-bearing and worth knowing before you open a PR:
- Anything that accumulates is append-only โ derive totals, never store a mutable counter
- Help text lives in the database, not in components
- Fail closed โ no fallback secrets, ever
- Code with no caller isnโt done
The reasoning behind each is in README-dev.md.
Deploying, every environment variable, the architecture and how the tests work: the
docs set.
Built for students, by a student.
License not yet specified.
Built with
AI tools
Prize Categories Entered
- Submitted
Best Use of Gemma 4
- Submitted

Best Open-Source AI Project