Backend 101

A course for new contributors who know Java and Spring but not this repository.

Read this first: this is not reference documentation. It is a guided reading of the real MotorPH backend — the fifteen-line boot class and the pom that explains itself, the Employees request vertical from controller to SQL, the security filter chain in its true execution order, tenancy down to the row-level policies, and the payroll engine at architecture level. 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 does this endpoint take, what is already configured" — you want Backend, not this. If you want the step-by-step recipe for building a new module, 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 Java and Spring basics — beans, annotations, JPA at a glance. But this codebase is large, and opening backend/src/main/java/ for the first time raises the questions this course answers: why does Flyway get its own database credentials, why is IllegalStateException deliberately not mapped to a friendly error, why is there a tenant column and a database policy for the same isolation, and why does the mapper configuration treat an unmapped field as a compile error.

The goal of this course is narrow and testable: by the end you can open any controller in backend/src/main/java/com/motorph/payroll/, trace its request down to the rows it touches, 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 and the Frontend 101 course: 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 five parts

Part 1 — Foundations (01–05). The skeleton: the boot class and the annotated pom, the single application.yml and its off-by-default doctrine, the ordered startup runners, the package map and the migrations, and the one error shape every failure wears.

Part 2 — The Employees vertical (06–09). The same feature Frontend 101 Part 2 reads from the browser, now read from the socket down: the sixty-filter list endpoint, the two query paths that share one predicate set, the Specifications and the repository, and the mapper boundary that refuses to guess.

Part 3 — Security, tenancy, and the machinery (10–14). The filter chain in execution order, the login path and its five independent defenses, tenancy in two layers — the request context and the database policies that back it — and the work the backend does with no request in flight.

Part 4 — The payroll engine, at architecture level (15–20). The shape of the engine and the reasoning in its decision comments: the frozen-payslip spine, the lifecycle gates and the snapshot rule, the pure computational core, compliance as versioned data, the true-up concept, and the settings that drive it all. The statutory rules and numbers themselves live in business-rules.md — this part sends you there rather than restating them.

Part 5 — Closing (21–22). How this code is tested — including the tests that deliberately never run in CI — and an honest map of what this course did not decode.

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 backend deeply; the customer portal, the platform-operator surface, and billing get pointers, not chapters. It is not a Spring tutorial: if beans and annotations are new, start with the annotations glossary and come back.

And one limit is a choice, not a shortage: the payroll and compliance part is taught at architecture level on purpose. You will learn the split of the pure calculator from the planner, the snapshot and cohort rules, and why the validators fail loud — the design, with the comments that justify it. The statutory tables, rates, and form mappings have a single home in business-rules.md and the compliance references, and the algorithms have a single home in the source. You leave able to navigate and reason about the engine; its numbers stay where they are maintained.

The lessons

Part 1 — Foundations

#	Lesson	You will be able to
01	Fifteen lines of boot, and the pom that explains itself	Read backend/pom.xml top to bottom and say why every non-obvious block is there
02	One application.yml, zero profiles	Predict what a fresh clone boots with, and name the env var that turns each subsystem on
03	Startup is a sequence: four runners, in order	Say what runs before the first request, and why the order cannot change
04	The package map, the entities, and the migrations	Name the five files a new endpoint needs, and place any migration in the schema's history
05	One error shape, and the 500 that is supposed to happen	Write down the wire response for any failure — and say which exception is deliberately not mapped

Part 2 — The Employees vertical

#	Lesson	You will be able to
06	GET /api/employees: sixty filters, one fields list	Read EmployeeController.list and write the grid's request by hand
07	EmployeeServiceImpl: one spec, two paths	Say when a list runs entities and when it runs a Tuple projection — and why the filters can never disagree
08	Specifications, escaped LIKEs, and the 409 that could have been a 500	Add a filter with the house helpers, and turn a uniqueness collision into a 409 with a field name
09	MapStruct at ERROR: the boundary that refuses to guess	Write a mapper that compiles under the house config, and state the four hand-written exceptions

Part 3 — Security, tenancy, and the machinery

#	Lesson	You will be able to
10	The filter chain, in execution order	List the filters a request crosses before @PreAuthorize, in execution order
11	The login path, hardened five ways	Trace login from socket to token pair and name the five independent defenses
12	Tenancy I: the context that follows the request	Explain how a tenant id reaches every SQL statement — and why missing means empty, not everything
13	Tenancy II: the database enforces it	Read one RLS policy and say why the app-layer filter alone was not enough
14	Schedulers, sockets, and mail: the work between requests	Enumerate the work this backend does with no request in flight, and whose tenant each piece runs as

Part 4 — The payroll engine, at architecture level

#	Lesson	You will be able to
15	The payroll spine: runs, payslips, and a ledger that never computes	Name the entities a payroll run touches — frozen, append-only, and derived
16	The run lifecycle: gates, snapshots, and a clock that keeps counting	Explain the snapshot rule, the schedule gate, and why generation is timed even when it throws
17	The pure core: a calculator and a planner with no dependencies	Say why the computational core is pure, and what that buys the tests
18	Compliance is data: cohorts, effective dates, and a validator that names names	Explain cohort versioning and what the coverage validator refuses to let a run do
19	Withholding and the true-up: why the final cutoff is different	Explain frequency-matched withholding and the true-up concept — the schedule decides, not measurement
20	Settings, reports, and the edges of the engine	Say where a default applies at read time vs compute time, and which features are deliberately not runs

Part 5 — Closing

#	Lesson	You will be able to
21	The test harness: containers, tenants, and honest exclusions	Run the right test command for what you changed — and know which tests CI never runs
22	The map and the gaps	Know what this course did not decode, and which document owns each of those areas

---

Start with lesson 01. It takes about twenty minutes and it starts from fifteen lines of Java.