# Code quality The four rules that apply identically to both projects: no dead code, comment the *why*, no starter scaffolding, and a mock is only a mock behind a seam. > Last verified: 2026-07-30 against commit `d3ec723`. --- ## 1. No dead code Unused variables, imports/usings, parameters, and private members are removed — not left behind, not commented out, and **not suppressed**. | Project | How it surfaces | Gate | | --- | --- | --- | | Client | `@typescript-eslint/no-unused-vars`, raised from eslint-config-next's default `warn` to **`error`** in `eslint.config.mjs` | Dead code **fails `npm run check`** | | Server | `CS0168` (declared, never used), `CS0219` (assigned, never read), `CS0169` (private field never used), `IDE0005` (unnecessary `using`) | The gate is **zero new warnings**, so dead code is a gate failure | **Delete it — don't silence it.** No `#pragma warning disable`, no throwaway discards, no `_ =` assignments to quiet an analyzer, no file-wide ESLint disable. Two sanctioned opt-outs, both narrow: - **Client:** a deliberately-unused binding is prefixed with `_` — `_event`, `catch (_err)`. - **Server:** a parameter that must exist to satisfy an interface or delegate signature but is genuinely unused stays, named conventionally, with a one-line `// why` only if the reason isn't obvious. When a lint disable is genuinely correct — a deliberate browser-only read after mount that trips `react-hooks/set-state-in-effect` is the real example in this codebase — use a scoped `// eslint-disable-next-line ` with a one-line reason on the line above. Never a file-wide disable, and never in preference to fixing the code. --- ## 2. Comment the *why*, never the *what* Code that needs a comment to be understood usually needs a **better name** instead. Reach for the name first, then a small helper, then a comment. **Don't** write a comment that restates what the code already says: ```csharp // ❌ restates the obvious // increment the retry counter retryCount++; ``` ```tsx // ❌ restates the obvious // set the access token setClientCookie(COOKIE_NAMES.ACCESS_TOKEN, token); ``` No XML-doc or JSDoc that merely echoes a function's name either. **Do** add a tight comment where a non-obvious decision, constraint, business rule, workaround, ordering or security requirement, or deliberate deviation is *not* evident from the code. Explain the reasoning, not the mechanics: ```csharp // ✅ captures a constraint the code can't express on its own // Payment gateway rejects amounts above 50M IRR per call; split larger settlements upstream. if (amount > MaxPerCallRial) … ``` The models to follow in this codebase: | File | What its comment earns | | --- | --- | | `client/src/app/[locale]/layout.tsx` | Why `` lives in the `[locale]` layout and not above it | | `client/src/lib/auth/token.ts` | Why the JWT `exp` check is UX-only and never a security boundary | | `client/src/layout/config.ts` | Why the two chrome-bar heights are measured rather than guessed, and must stay in sync with the bars | | `client/middleware.ts` | Why the matcher lists bare `'/'` explicitly alongside the catch-all regex | Delete comments that no longer match the code. A wrong comment costs more than no comment. --- ## 3. Don't reintroduce starter scaffolding Both projects were derived from open-source starters. Their branding, demo/showcase pages, and `_TITLE_`/`_DESCRIPTION_` placeholders were **intentionally removed**. Don't add them back — not as a convenience, not while editing docs, not as an example. Specifically: - No placeholder page, showcase route, or "example component" gallery. - No `_TITLE_` / `_DESCRIPTION_` / lorem-ipsum copy anywhere, including in message files. - No starter README boilerplate reinstated into a project README. - `PlaceholderScreen` exists for a genuinely not-yet-built screen and must not be reachable from a shell's navigation. `/admin/notifications` is the current example: it is a placeholder, and it is deliberately absent from `AdminLayout`'s nav for that reason. --- ## 4. A mock is only a mock behind a seam Some integrations are intentionally out of scope and must be **mocked, not invented**: real PSP and BNPL connections, the Shahkar / MoH / INO / criminal-record vendors, MinIO/S3 credentials, the سامانه مودیان enrollment. Reaching one is not a blocker. The only sanctioned form of "not real yet" is: 1. **An interface.** Server: an interface in `Application/Contracts/`, implemented twice, selected by configuration in `AddCrossCuttingSeams` — and **the default is the mock, with a typo falling closed to the mock**. Client: the domain's `Api` interface in `services/{domain}/types.ts`, implemented by `clientApi.ts` and `mockApi.ts`, selected in `apis/index.ts` by `USE_{DOMAIN}_MOCK`. 2. **Selection by registration, never by branching.** No `if (mock)` inside a handler, hook, or component. Swapping a mock for the real thing is a one-line registration change and touches no caller. 3. **A record**, in `docs/status/`: the seam (interface name + file), what is faked, why, the config keys it reads, and **step-by-step how to make it real** — which provider, which settings, which methods, what to test. An unrecorded mock is a defect, because the next agent cannot tell a deliberate stand-in from a bug. Two mocks in this repo are **deliberate MVP endpoints, not stand-ins waiting for a vendor**: `ICredentialVerifier` / `ILicenseVerificationService` stay mock because manual MoH / INO / eNamad review *is* the intended MVP — there is no public B2B API. Don't "finish" them. --- ## 5. Scale and cost are part of correctness Every decision should consider what it costs at scale, not only whether it works once: **Server** — indexing, pagination on every unbounded list, caching read-heavy and reference data behind the cache seam, idempotency and locks on the money path, the DB constraint as the authoritative backstop behind every friendly pre-check. **Client** — query caching with a deliberate `staleTime` so you never refetch what you already hold, invalidation on mutation, re-render cost (stable references, `select` to subscribe to a slice, state colocated low), and bundle size. And in both: the seam that lets a mock become real without touching a caller. --- ## 6. Configuration lives in files, not a secret store `dotnet user-secrets` is **not used** in this repo, and the `` was removed from `Baya.Web.Api.csproj`, so that store **is not read at all**. Any instruction telling you to set a value with `dotnet user-secrets` is stale. | Where config lives | What | | --- | --- | | `server/src/API/Baya.Web.Api/appsettings.*.json` | Server config, including dev crypto keys | | `client/.env.development` / `.env.production` | Client config | | root `docker-compose.yml` | The deployment's container-specific overrides | This is a deliberate pre-launch trade for a demo deployment, which means **the repo contains live credentials**. Before onboarding real users they must be rotated and the secret half moved out of git — see [`DEPLOY.md`](../../../DEPLOY.md) "Going to Production". Never hardcode a secret in code either way: keys, connection strings, and tokens come from configuration bound to typed settings, never a literal in a handler, service, or component. One value is load-bearing and must never change: `Seams:FieldEncryption:Key` / `:HashKey` decrypt all existing PII and derive the phone-lookup hash. Changing them makes every PII read throw and every phone lookup miss.