development guide

Layout of the code, patterns, and how to extend it.

Related: Build & Deployment, Mock Data System, Adding New Features.

git clone https://github.com/tashifkhan/jportal
cd jportal/jportal
npm install

jportal/
├── src/
│   ├── components/     # features, MockWebPortal.js, theme-*, ui/
│   ├── assets/fakedata.json
│   ├── hooks/cloudflare.ts
│   ├── lib/api.ts utils.js
│   ├── stores/theme-store.ts
│   ├── utils/theme-presets.ts fonts.ts
│   ├── App.jsx
│   └── main.jsx
├── public/artifact public/icons public/pwa-icons
├── vite.config.ts
└── index.html

MockWebPortal is .js, not .jsx. Theme store is src/stores/theme-store.ts, not src/lib.

Main entry flow#

flowchart TD
  main["main.jsx"] --> App
  App --> Stats["/stats"]
  App --> Gate{"isAuthenticated"}
  Gate -->|no| Login
  Gate -->|yes| Auth["AuthenticatedApp"]

const realPortal = new WebPortal({
  useProxy: true,
  proxyUrl: "https://jportal-cors-proxy.onrender.com",
});
const mockPortal = new MockWebPortal();
const activePortal = isDemoMode ? mockPortal : realPortal;

Methods match jsjiit (get_attendance, get_sgpa_cgpa, …), not a fictional get_grades().

Authentication state flow#

flowchart TD
  Mount["stored creds"] --> RealLogin["realPortal.student_login"]
  Form["Login submit"] --> RealLogin
  Demo["Try Demo"] --> Mock["isDemoMode"]

Multi-layer state pattern#

flowchart TD
  App["auth flags"] --> AA["feature useState"]
  AA --> Pages
  Store["useThemeStore"] --> Theme
  QC["QueryClient"] --> Cloudflare

Attendance goal example stays on AuthenticatedApp.

Standard feature module structure#

flowchart TD
  Comp["Feature.jsx"] --> Effect["useEffect w.method"]
  Comp --> Select["semester Select"]
  Comp --> Cache["keyed state"]

Every module gets w, data, setters, metadata, selection, UI flags.

The w prop#

flowchart LR
  Page --> W["w"]
  W --> Real["WebPortal"]
  W --> Mock["MockWebPortal"]

Typical fetch: set loading, await w.get_something, set data, catch, finally clear loading.

Props drilling#

flowchart TD
  AA --> Page --> Child["AttendanceCard"]

Theme uses Zustand instead:

const { themeState, setThemeState } = useThemeStore();

File: src/stores/theme-store.ts.

username, password, attendanceGoal, Zustand persist for theme.

LoginError branches in Login.jsx and App.jsx. Toasts via sonner Toaster in App.

.jsx for most UI, .ts/.tsx for theme and analytics. Name caches attendanceData, setters setAttendanceData.

flowchart TD
  Hash["#35;/"] --> Att["#35;/attendance"]
  Hash --> Gr["#35;/grades"]
  Hash --> Ex["#35;/exams"]
  Hash --> Sub["#35;/subjects"]
  Hash --> Pr["#35;/profile"]
  Hash --> St["#35;/stats"]

Header top, Navbar bottom.

ESLint 9 with React, hooks, refresh, TanStack Query plugin.