Frontend 101

A course for new contributors who know React but not this repository.

Read this first: this is not reference documentation. It is a guided reading of the real MotorPH frontend — the provider stack, the routing shells, the enterprise grid that runs forty list pages, the 700-line Employees.tsx, and the HR analytics system down to its 3D scene. All code is quoted inline from the working tree, so you can read the whole course without the repository open, though it lands harder with the files beside you.

If you want reference material instead — "what props does this take, what is already configured" — you want Frontend, not this. If you want the step-by-step recipe for building a new module page, that is Build a module page. The three are complements: this course builds the mental models, those pages are what you consult once you have them.

Who this is for

You are comfortable with React — components, hooks, props, effects. But this codebase is large, and opening frontend/src/ for the first time raises the questions this course answers: why are there four layout shells, why does the employees list live in none of the three state stores, why does every chart pass isAnimationActive={false}, and why does a comment forbid putting the toolbar where it would obviously go.

The goal of this course is narrow and testable: by the end you can open any page in frontend/src/pages/, say which system it is built on and why, and know which file to copy when you build your own.

How each lesson works

Every lesson has the same four beats:

1. Orient — what problem the file you are about to read solves, and why it exists at all.
2. Read — the real code, quoted inline and annotated. Every quote in this course was copied from the source tree, not written from memory.
3. Predict — before a resolution is shown, you write down what you think happens. A wrong prediction is the only reliable signal that a model in your head is broken.
4. Recap — the rules, bolded, each with the incident or in-code comment that justifies it.

There are no labs. This is a decoded tour in the style of the Learn DevOps Track B chapters: the code in front of you is the production code, and the comments inside it are the primary sources. Almost every rule in this course exists because something broke once — the lesson tells you what.

The three parts

Part 1 — Foundations (01–06). The skeleton every page hangs on: the provider stack, the router and its four shells, the permission system, the data layer, the three state stores, the shell and theme. Read these in order; everything later assumes them.

Part 2 — The enterprise grid (07–13). One system runs some forty list pages. You read it from the column contract up through ServerDataGrid and useEnterpriseGrid, then read Employees.tsx — the biggest grid page in the repo — top to bottom, satellites and all.

Part 3 — HR analytics (14–20). The newest and most decision-dense corner of the frontend: the visual token system, the chart wrappers and their Recharts scars, the drilldown drawer, the URL-as-state cross-filter, the 3D department landscape, and the PDF export pipeline.

Part 4 — Closing (21–22). The house form style, then an honest map of what this course did not cover.

What you need

• The repository checked out. Nothing needs to be running — every lesson works on a cold clone.
• An editor for jumping into the files, though all quoted code is inline.
• About ten hours end to end, in 15–45 minute lessons.

Honest limits

This course reads code; it does not run it. It decodes the tree as it stood when the course was written, and code moves — when prose and source disagree, the source is right, and the comment trail inside the files is the primary documentation. It covers the ERP-facing frontend deeply and the portal, super-admin, and public marketing surfaces not at all. And it is not a React tutorial: if hooks and props are new, start with the React docs and come back.

The lessons

Part 1 — Foundations

#	Lesson	You will be able to
01	The stack, from main.tsx up	Name every provider in the tree and say why the order matters
02	App.tsx decoded: a hundred routes, four shells	Add a route to the right shell and explain what page() buys you
03	Who can see what: the permission system	Trace one permission from login to a hidden button — and say how a user is granted it in the first place
04	The data layer: one client, seventy wrappers	Add an endpoint the way the other seventy were added
05	Three kinds of state, on purpose	Say where any given piece of state lives, and why
06	The shell and the theme	Read theme.ts and know which token to change — and which second file must move with it

Part 2 — The enterprise grid

#	Lesson	You will be able to
07	The grid problem, and the column contract	Read an EnterpriseGridColumn[] and know exactly what the server will be asked for
08	ServerDataGrid decoded	Explain what happens between a scroll event and a network request
09	useEnterpriseGrid decoded	Wire a new page onto the hook and explain every field it returns
10	Tabs, toolbars, and the two load-bearing conventions	State both conventions and what breaks when each is violated
11	Employees.tsx decoded: columns, tabs, params	Read the biggest grid page in the repo top to bottom
12	Employees: the drawers, dialogs, and exports	Explain why the detail drawer re-fetches, and ship a CSV/PDF export
13	Two import modals, and which page to copy	Choose between the shared ImportModal and a bespoke one, and know which page to copy for your own

Part 3 — HR analytics

#	Lesson	You will be able to
14	The analytics page decoded	Explain why every tab is lazyMount unmountOnExit, and where the data comes from
15	The visual language: tokens before charts	Pick the right color for a new series without guessing
16	Panels, tiles, and a hand-rolled sparkline	Say what the silent-zero bug is and how AnalyticsPanel prevents it
17	The chart wrappers, and the Recharts scars	Use the five wrappers and recognise four Recharts failure modes on sight
18	The drilldown drawer decoded	Trace a KPI click to a paginated record list and a nested drawer
19	The URL is the state	Add a new cross-filter producer without adding any state
20	The 3D landscape and the PDF button	Explain every defensive line in the R3F scene and the html2canvas pipeline

Part 4 — Closing

#	Lesson	You will be able to
21	Forms, decoded through one drawer	Build a form drawer that matches the house style
22	The map and the gaps	Know what this course did not cover, and where to go next

---

Start with lesson 01. It takes about twenty minutes and it starts from main.tsx.