Answers to the eleven D2 questions (instructions) as built. Demo: Week 7, 20–30 min, live. Related: architecture.md · supplier-service.md · wireframes · demo script + curl walkthrough

flowchart LR
    subgraph M["Merged"]
        UA["user-service: signup + OTP email ·<br/>login · JWT + RBAC · owner/admin ·<br/>purge · demo-account seed"]
        SA["supplier-service: schema + seed ·<br/>browse/search/filter/sort/page ·<br/>JWT role gate · CRUD writes"]
        WA["web: auth + OTP dialog · suppliers<br/>with admin CRUD modals · admin pages"]
    end
    subgraph R["In review"]
        PROF["#149 profile screens"]
        UPD["#157 account updates (#92)"]
    end
    subgraph O["Deferred"]
        LOGOUT["logout denylist #90"]
        RESET["recovery / reset #94"]
    end
    classDef ok fill:#1a7f37,color:#ffffff
    classDef rev fill:#9a6700,color:#ffffff
    classDef gap fill:#cf222e,color:#ffffff
    class UA,SA,WA ok
    class PROF,UPD rev
    class LOGOUT,RESET gap

Requester/courier are modes of USER, not roles — one account does both, no re-login (F5.1.1).

• Enforced where: the JWT role claim travels with every request; each service checks it server-side (user-service #144, supplier-service #143).
• Adding a role later (mentor question — scalable roles): add one Role enum value and authorization logic in SecurityConfig files and the UI.
• Can an admin edit a user's profile? No — admin powers are role change and removal only; profile fields are self-service via /users/me.
• Can a normal user edit suppliers? No — supplier writes require admin role; a direct API call gets 403 problem+json (see Part 2 §4).

PostgreSQL 17 + Spring Data JPA. Why:

• Integrity rules enforced by the database: unique email/username (including soft-deleted rows by using soft-delete flag), role checks (NFR4.1).
• Flows are transactional multi-row writes: verify→insert, lockout counters, dependents-first purge. A failed write rolls back — no partial state.
• 60 000 accounts (NFR2.1) and operations within 2 seconds (NFR3.1) achievable.

Schema (bold = required / NOT NULL, rest nullable):

erDiagram
    users {
        bigint id PK "req"
        text email UK "req - eXXXXXXX at u.nus.edu"
        text username UK "req - 3-30 A-Za-z0-9_"
        text password_hash "req - BCrypt"
        text role "req - USER or ADMIN or OWNER"
        int failed_login_attempts "req - default 0"
        timestamptz locked_until "opt - null = unlocked"
        timestamptz created_at "req"
        timestamptz deleted_at "opt - null = active"
        bigint version "req - optimistic lock"
    }
    pending_signups {
        bigint id PK "req"
        text email UK "req"
        text username "req - not unique, first verify wins"
        text password_hash "req - BCrypt"
        text code_hash "req - BCrypt-hashed OTP"
        timestamptz last_sent_at "req - resend cooldown origin"
        timestamptz expires_at "req - 10 min, never extended"
        int attempts "req - max 5 per row, resends included"
    }
    account_tokens {
        bigint id PK "req"
        bigint user_id FK "req"
        text token_hash "req"
        text kind "req - PASSWORD_RESET or RECOVERY"
        timestamptz expires_at "req"
    }
    token_denylist {
        text jti PK "req"
        timestamptz expires_at "req"
    }
    users ||--o{ account_tokens : "has"

Why these relations:

• pending_signups has no FK to users on purpose: with insert-after-verify (F1.1.2) there is no user row yet — the OTP state is keyed by email; the users row appears only on successful verify.
• users 1—* account_tokens: a user may hold several outstanding hashed reset/recovery tokens (F4.1); FK ties their lifecycle to the account (purged together).
• token_denylist stands alone: it's token-scoped (keyed by jti), not user-scoped — reserved for logout.

Credential storage (NFR1.1): only BCrypt hashes persist — passwords and OTP codes; JWT_SECRET and the owner-setup token live in env, never the DB; codes/tokens/secrets are never written to logs (mentor question).

✍️ Open inconsistency to answer if probed: D1 NFR1.2 says emails are hashed too — they're stored plaintext because email is the login/OTP identifier. Team to amend the NFR or revisit.

Account lifecycle (F3.1.1–F3.1.3, F4.1):

stateDiagram-v2
    [*] --> Pending: signup (202)
    Pending --> Active: OTP verified (users row inserted)
    Pending --> [*]: expired / 5 wrong codes / identifier taken
    Active --> Deleted: self delete or admin remove (soft)
    Deleted --> Active: login within 30 d recovers
    Deleted --> [*]: purge daily 03:00, day 31

Token-based (JWT, HS256, shared secret). Self-contained claims let every microservice and the web UI read the caller's role locally — stateless, no rerouting allowing for less latency.

• Every request is validated by the filter chain (#144): signature (HS256 only), exp present + unexpired, numeric sub, known role — then URL rules apply (/users admin routes → hasAnyRole("ADMIN","OWNER"), fail-closed default authenticated()). Violations → problem+json 401/403.
• IDOR (User A vs User B): self-service routes are /users/me — there is no id parameter to tamper with; the target is always the verified sub. The only id-taking read, GET /users/{id}, returns username alone.
• Sign-up (F1.1): unique email/username (F1.1.1), u.nus.edu domain, password 10–50 with upper+lower+digit (F1.1.3), all violations returned with exact reasons (F1.1.5–6). Then OTP by email (F1.1.2):

sequenceDiagram
    actor Student
    participant SPA
    participant US as user-service
    participant SMTP as Mailpit / Gmail

    SPA->>US: POST /auth/signup
    US-->>SPA: 202 (row parked in pending_signups)
    US->>SMTP: 6-digit code (10 min, 5 attempts, BCrypt-hashed)
    Student->>SPA: enter code
    SPA->>US: POST /auth/signup/verify
    US-->>SPA: 201 (users row inserted)

The SPA side is a dialog over the register card (six code boxes, "Resend code", per wireframes signup.png) — built in #150 as the sign-up/OTP half of #109, which keeps logout and token handling.

Who may move a pending sign-up along — decided by the User Service owner in #150's reviews (options Q&A), after review found the first shape unsafe:

Why, and what was rejected: the original "last request wins" let anyone who knew an address overwrite a pending sign-up's username/password, so the code the real student received created an account holding someone else's password. Reversing it to "first request wins, later ones only resend" was tried and dropped — it merely reverses who has to move first, since a planted row would then be what the student's own sign-up completed into. Matching on the details the requester supplied is what proves it is the same request without a token for the SPA to carry.

Two follow-on rules from the same review, both about a row that outstays its usefulness: a resend replaces the code but not expires_at, so a row lives at most OTP_TTL from creation and always reaches the takeable state (otherwise its creator could resend once per cooldown for ever and hold the address, while its owner kept getting a 409 telling them to wait for an expiry that never came); and verify discards a pending row whose email or username was taken meanwhile, since it can never complete and used to lock whoever lost a username race out of their own address for the rest of the TTL. Consequence accepted on purpose: a late resend hands out a short-lived code, and the email and the 202 quote the seconds actually left.

5 wrong codes → 429, signup discarded (counted per pending sign-up, resends included). Mail failure → 502, rolled back — on a resend that leaves the previous code live. Provider: Gmail SMTP, with a Mailpit container as the local target (inbox at localhost:8025) — switched by .env only.

• Login (F5.1): username-or-email + password; 5 failures → 15 min lockout (429 + Retry-After); errors name the cause (decided #148 — the lockout countdown reveals existence anyway); login within 30 days recovers a soft-deleted account (F4.1).

Routes and response types (mentor ask: which fields does each operation return):

Same token, verified independently by each service with a local JwtVerifier — no runtime call back to user-service, no shared library coupling:

sequenceDiagram
    actor A as ADMIN
    actor U as USER
    participant SPA
    participant US as user-service
    participant SS as supplier-service

    A->>SPA: login
    SPA->>US: POST /auth/login
    US-->>SPA: JWT (role: ADMIN, 1 h)
    SPA->>SS: POST /suppliers + Bearer
    SS->>SS: verify signature locally, read role
    SS-->>SPA: 2xx

    U->>SPA: login
    US-->>SPA: JWT (role: USER)
    SPA->>SS: POST /suppliers + Bearer
    SS-->>SPA: 403 problem+json

The supplier-side gate merged in #143 (2026-09-29) — the diagram above is live behaviour on main, including the ADMIN-or-OWNER rule on writes (owner is admin-equivalent, decided in that PR's review).

• Live now: GET /users/me (own data incl. role), DELETE /users/me (confirm dialog in UI, then soft delete).
• Update flows (#92, screens in #149): edits re-validated like sign-up (uniqueness F2.1.2, policy re-check), gated by an OTP to the existing email first (F2.1.1), new email confirmed by its own OTP (F2.1.3), password double-entry.
• Protected fields (role, status, id — the P1.5 question): request DTOs are allow-lists — PATCH /users/me will bind only email/username/password, so a request carrying "role": "ADMIN" has no field to land in. Already live at sign-up: a role in the body is ignored.

Applies to every endpoint that changes an account today (DELETE /users/me, the admin PATCH / DELETE /users/{id}, sign-up and owner setup), and is what the profile-update endpoint (#92) will plug into — there is no PATCH /users/me yet.

1. Authentication: JwtAuthenticationFilter checks the bearer token on each request: HS256 signature with the shared secret, an exp that is present and not passed, a numeric sub, a known role. A bad token is a 401 problem+json. SecurityConfig then requires a signed-in caller on every route except /auth/** (sign-up, login, owner setup — public by design) and /actuator/health.
2. Authorization: URL rules in SecurityConfig, checked before any controller code runs:
   • GET /users/* and DELETE /users/me — any signed-in user.
   • everything else under /users, including PATCH /users/{id} (role change) — ADMIN or OWNER only; others get 403. Unlisted methods fail closed.
   • /users/me routes act on the caller's own account: the ID comes from the token's sub, never from the request.
3. Validation: request bodies are records checked with Jakarta Validation (@Valid), e.g. the password rules via @Pattern in AccountRules. ProblemDetailAdvice turns failures into one 400 problem+json (RFC 9457) listing each broken rule, sorted by field; an unreadable body is 400 "Request body is missing or malformed". Business rules then run in the service (uniqueness including soft-deleted accounts, "OWNER can't be changed", …).
4. Concurrency: User has a @Version column (optimistic locking). Each save checks that the row hasn't changed since it was read; if another request saved it in between, the save fails with OptimisticLockingFailureException, answered as 409 "The account was changed by another request; reload and try again". Example: one admin changes a user's role while another admin removes that user — without the check, the role change (made from a copy read before the removal) could write the account back as active. Login's own counter update uses a row lock instead (LoginAttempts), so parallel wrong passwords all count.

• User ID: never taken from the request. /users/me routes get the caller's ID from the verified login token's sub claim (JwtAuthenticationFilter → CallerId.from), so there's no way to name someone else's account. The id column is also generated by the database.
• Role:
  • Sign-up's request type (SignupRequest) has no role field, and AuthService always creates Role.USER. A role sent in the body is dropped (there's a test for this in AuthControllerTest).
  • The only way to change a role is the admin endpoint (§6).
  • The authorization rules use the role in the signed token, which the server issued, so a client can't make one up.
• Account status: there's no field a client can set.
  • deleted_at changes only through softDelete (on DELETE /users/me or an admin's removal), or when logging in within 30 days recovers the account.
  • The lockout counters change only inside login (LoginAttempts).
  • created_at can't be updated (updatable = false).
• Allow-list request types: each request type lists only the fields it accepts. For example, UpdateRoleRequest binds only role.

Run against the live stack on 2026-09-30 (main + the demo-account seeder); the responses are the service's actual output. $USER_TOKEN is a normal user's login token, $ADMIN_TOKEN an admin's.

flowchart LR
    T["setup token in env<br/>known only to the developers"] -->|"X-Setup-Token header<br/>while OWNER_SETUP_TOKEN is set"| O["OWNER(s)<br/>POST /auth/setup-owner"]
    O -->|"dashboard promote button"| A["first ADMIN"]
    A -->|"owners and admins<br/>promote / demote"| MORE["user ↔ admin"]

The first owner comes from the setup endpoint; the first ADMIN is then promoted by an owner through the admin dashboard.

• The route: POST /auth/setup-owner, in OwnerSetupController and OwnerSetupService. It takes email, username and password, validated with the same rules as sign-up. It is the only way to create an OWNER.
• What controls it:
  • Shared secret: the request must carry an X-Setup-Token header matching the server's OWNER_SETUP_TOKEN, compared in constant time with MessageDigest.isEqual. A wrong or missing token gets a 403.
  • Off without a token: if the server has no token configured, the endpoint returns 503. The intended practice is to set the token, create the owner, then unset it.
  • No duplicates under concurrent calls: a database advisory lock (acquireSetupLock) serialises setup calls, so two at once can't both pass the uniqueness checks.
• Things to know:
  • Each call with a valid token creates another owner. The team removed the "only when no owner exists" limit.
  • The token never expires; expiry was added and then deferred.
  • The route sits under /auth/**, which is open to anyone, so the token is the only protection.

1. The request: an ADMIN or OWNER opens /admin and clicks Promote to Admin, then confirms in a dialog. The web app sends PATCH /users/{id} with {"role":"ADMIN"}.
2. Access check: SecurityConfig allows it only if the token's role is ADMIN or OWNER; anyone else gets a 403.
3. Business rules (AdminService.changeRole):
   • Asking for OWNER is refused (403, "OWNER can only be granted through owner setup").
   • The target must be an active account, or it's a 404.
   • The target must not be an OWNER (403).
   • A promotion to the role the user already has returns 200 without saving anything.
   • A simultaneous change that loses the race gets a 409, via the @Version check.
4. When it takes effect: the new role is saved immediately, but permissions come from the login token. So the promoted user gets admin access at their next login, and their current token keeps the old role for up to an hour.

No — the server refuses them, and the web app doesn't show them the page.

• The web checks only shape the UI. The server check is the real control: calling the API directly with a USER token still gets 403.
• Because the page check uses the current role (/users/me) but the API trusts the role in the token, a demoted admin loses the /admin page on their next page load but can keep calling admin APIs with their old token until it expires (up to 1 h) — the stale-role case in the table below.

Edge cases:

PostgreSQL 16 + JPA. Why:

• Supplier metadata is fixed and structured — it comes straight from the course CSV; every CSV column maps to a typed column (below), nothing document-shaped.
• One genuinely relational need: a supplier has multiple categories (CSV Type like Food/Coffee is split into join-table rows) — F1.1.1 says "categories", plural.
• Capacity (NFR2.1): 1 000 suppliers — NUS-scale, not a million-row marketplace. At that size a sequential scan clears the 5 s listing bound (NFR1.1) with no indexes (supplier-service.md D7); revisit only if the target grows.

Schema (required = NOT NULL; everything else optional — real CSV rows have gaps):

erDiagram
    Suppliers {
        bigint id PK "req - the identity"
        text name "req - NOT unique, see branches note"
        text category "opt - raw CSV Type cell"
        text building "opt"
        text floor "opt"
        text location_description "opt"
        double latitude "opt - distance sort + Order 1 km rule later"
        double longitude "opt"
        time starting_time "opt - CSV 0900hrs parsed to TIME"
        time closing_time "opt"
        text image_url "opt"
        text supplier_description "opt - admin-filled"
    }
    SupplierCategories {
        bigint id PK "req - shares supplier PK"
        text category PK "req - one row per split Type value"
    }
    Suppliers ||--o{ SupplierCategories : "categorised as"

• Types (mentor ask): text for names/locations, double lat/lng (real coordinates — Order Service's 1 km rule needs them), SQL TIME for opening hours parsed from the CSV's 0900hrs format, join rows for categories.
• Supplier identity (mentor question — same names, branches): the id is the identity; name is deliberately not unique. Starbucks @ YIH and Starbucks @ UTown are two rows, same name, distinguished by building/floor/location_description and coordinates.
• Validation (mentor question): name is the only hard-required field (DB NOT NULL). On the CRUD endpoints, Bean Validation enforces it plus format checks (numeric coordinate ranges, time format) — a request that bypasses the UI is rejected by the backend with 400 problem+json whose detail lists every failing field, which is also what the UI shows.

Key patterns (all live): paged browse · search by name · filter by category · sort by name asc/desc · sort by distance ("nearest to me": UI sends the browser's lat/lng, ordering is Haversine in SQL) · supplier details from the list payload · no match → 200 with an empty page, UI shows the empty state (F2.2.1).

Denied requests: missing/invalid token → 401, wrong role → 403 — problem+json with the reason in detail (a regular user calling a restricted endpoint directly gets the 403, not a hidden button).

• Delete semantics — decided (team meeting, 2026-09-29): F1.1.3 is a hard delete. Future guard once the Order Service exists: deleting a supplier with outstanding orders is rejected with an error — referential integrity by refusal, not soft-delete. (supplier-service.md D5 records the decision.)
• The three write endpoints shipped in #153 (merged 2026-09-30, closing #106): Bean Validation on SupplierRequest, 404 problem+json for a missing id, and a demo-crud.sh walkthrough alongside the service.
• Backend works without the UI: every operation above is demoable with curl while the web container is stopped — the demo script logs in against user-service for a real JWT, then drives every supplier endpoint, showing accepted and rejected calls.

Full flow: login → JWT → supplier API → database, with role-appropriate outcomes (Part 1 §4 diagram).

• UI reflects the role — non-admins see no "add supplier" button and no edit/delete on supplier cards — and the backend enforces it independently: the same action via curl returns 403 problem+json. Restricted buttons are hidden and the endpoints are gated (the mentor's "merely hidden in the UI?" question).
• Accepted/rejected pairs per role are scripted in the demo script.
• UI in place: the Admin Dashboard nav link / mobile tab appears for ADMIN and OWNER (#147); supplier management lives on the Suppliers page (add, plus edit/delete on supplier cards — modals shipped with #153). The admin dashboard shows only the Users section for now — its Suppliers section was removed (#158, Ryan Ang, 2026-09-30).

• Workflows live on real API data (no mocks): browse, search, filter, sort, paginate, details; admin create/edit/delete modals wired to §3's endpoints (#153).
• Desktop NavBar / mobile bottom TabBar; every screen at both widths.
• Demo data: seeded (#155) — DemoAccountsSeeder inserts 1 owner, 3 admins and 100 users at startup when USER_SEED_DEMO=true (off by default; passwords documented in the user-service README, local/demo only) — so pagination, search and role scenarios look real.

1. Before demo: merge #149 (profile screens) and, if ready, #157 (#92's account updates). Everything else on the old list has merged — #143, #150, supplier writes (#153), the demo seed (#155), the /admin nav link (#147).
2. Next: the rest of #109 (logout, token handling — its sign-up/OTP screens shipped in #150) · logout denylist #90 · account update #92 — in review as #157, reusing OtpService and the pending-table-per-operation shape · recovery/reset #94.
3. Prepared answers: NFR1.2 email-hashing inconsistency (Part 1 §2) · supplier rename vs order history (delete is decided; rename/snapshot question goes to Order Service design).

Migrated from Lark 2026-09-29 (original frozen); refreshed from the PR record and the 2026-09-29 team meeting. Diffs live on the PRs.