Ultimate FFCS

---

What is FFCS?

FFCS (Fully Flexible Credit System) is VIT's biannual course registration system where students race to register for the best professor-slot combinations before they fill up — manually cross-checking hundreds of possible timetable arrangements. Ultimate FFCS Planner automates that entirely.

---

Features

Generation

• Backtracking DFS with MRV heuristic finds every valid conflict-free combination across 10+ courses with multiple professor options
• Runs in a Web Worker so the UI stays responsive; a generating screen holds until results land
• Ranking profiles (Balanced, Half Days, Minimize Gaps, Early Finish, Late Start) score every week 0–100 from half days, gaps, finish time, start time, daily balance and your professor ranking
• Full constraint system: blocked windows, no-classes-after time, per-day start/end times, professor avoids/locks, max gap slots

Course input

• Catalog search against the live Supabase-backed semester catalog. Pick your program once and its courses and professors come first under "Your program"; every other course stays searchable under "All courses", with duplicate options merged
• Smart paste parser handles WhatsApp-forwarded course lists in any text format
• CSV / XLSX import, manual entry, and a VTOP bookmarklet import

Results

• Slot matrix timetable with colour-coded courses and cell-level detail panels
• Swap a professor right under the grid: same week, the grid updates in place
• Week layouts ("shapes") and professor combos, side-by-side comparison of up to 3 timetables
• Zero-results diagnostic: names the courses or constraints responsible when no valid combination exists, with one-tap fixes

Onboarding

• Guided tour across planner and results; on an empty plan it can load sample courses, run a search, and clear them at the end unless kept

Export & share

• PDF, PNG, JSON, iCal (weekly repeating events for Google/Apple/Outlook Calendar)
• Copy the slot list for VTOP registration
• Persistent share links for course lists and specific timetables

Multi-campus

• VIT Chennai + VIT Vellore: standard slot catalog (Mon–Fri)
• VIT AP: Tue–Sat week, non-uniform lab durations
• VIT Bhopal: Bhopal slot catalog

---

Tech Stack

Framework	Next.js 14 App Router
Language	TypeScript
Styling	Tailwind CSS + in-house fp-ui primitives (theme tokens in src/app/fp-tokens.css)
State	Zustand + localStorage persistence
Database	Supabase (Postgres + RLS)
Generation	Web Worker (backtracking DFS)
Parsing	PapaParse, SheetJS, LZ-string
Export	html-to-image, jsPDF
Hosting	Vercel

---

Architecture

src/
├── app/                        # Next.js App Router
│   ├── [campus]/               # Static slot-timing pages per campus (SEO)
│   ├── planner/                # Courses + preferences, "Find my weeks"
│   ├── results/                # Browse, swap, export, share generated weeks
│   ├── compare/ saved/ settings/ support/
│   ├── timetable/[id]/         # Shared timetable view (public, no auth)
│   ├── admin/                  # Bulk catalog upload + usage stats (developer only)
│   └── api/
│       ├── catalog/search/     # Whole campus/semester catalog (edge-cached)
│       ├── catalog/semesters/  # Semester metadata
│       ├── share-timetable/    # Share link creation + resolution
│       ├── events/             # Anonymous usage events (allowlisted props)
│       ├── vtop-import/        # VTOP bookmarklet hand-off
│       └── admin/              # Bulk course upload, auth
│
├── engine/                     # Generator, conflicts, zero-result analysis,
│                               # metrics, ranking, per-campus slot catalogs, worker
│
├── components/fp-ui/           # Design-system primitives, app shell, program picker
│
├── features/
│   ├── planner/fp/             # Search, paste, file, manual tabs; preferences
│   ├── programs/               # Program names + "Your program / All courses" scoping
│   ├── courses/                # Merging catalog options into the plan
│   ├── import/ paste-import/   # CSV/XLSX pipeline, free-text parser
│   ├── results/                # Slot matrix, block details, iCal dialog
│   ├── tour/                   # Guided tour + sample courses
│   ├── landing/ campus/        # Home page, campus pages
│   └── vtop-scraper/           # VTOP bookmarklet
│
├── lib/                        # Supabase clients, catalog cache, usage events, iCal
├── utils/                      # Share encoding, PNG/PDF export
├── store/useAppStore.ts        # Zustand store — app state + persistence
└── hooks/                      # useGenerator, useMediaQuery

supabase/migrations/            # Versioned SQL migrations

Generation algorithm in brief: courses are sorted by ascending option count (MRV) before search. At each DFS node, violatesOptionHardConstraints prunes infeasible options immediately; conflictsWithExisting prunes time overlaps against already-placed courses. Soft constraints (max gap) are deferred to complete-timetable checks to avoid premature pruning. Results are scored through a weighted metric pipeline (src/engine/ranking.ts) and returned sorted by descending score.

Catalog and programs: the client fetches a campus's whole active catalog once (src/lib/catalogCache.ts) and filters it locally per keystroke. Each professor option carries a program code (BCE, BYB, … or ALL for untagged); the program picker lists only codes present in the catalog, and friendly names live in src/features/programs/programCatalog.ts.

---

Local Development

Prerequisites: Node.js 18+, a Supabase project

git clone https://github.com/mrRR7/ffcsmaker
cd ffcsmaker
npm install

Copy .env.local.example to .env.local and fill in your Supabase URL, anon key, service role key, and an ADMIN_SECRET_KEY.

Run the SQL files in supabase/migrations/ against your Supabase project, then:

npm run dev

Checks: npm run typecheck, npm run lint, npm test (Node's built-in test runner).

The admin panel at /admin handles semester and course data upload — developer-only, protected by ADMIN_SECRET_KEY. Re-uploading a semester updates courses in place and replaces options only for the program codes present in the upload.

Kill switch: NEXT_PUBLIC_PROGRAM_PICKER=off hides the program picker and searches every course. It's read at build time, so changing it needs a redeploy.

---

Contributing

Source-visible. Not actively seeking contributions — but bug reports via issues are welcome.

---