ProcureLinc-Mobile-App/docs/ARCHITECTURE.md

ProcureLinc — Architecture Guide (as-built)

This is the as-built companion to ARCHITECTURE_AUDIT.md. The audit is the blueprint (what was wrong, what to build); this document is the map of what now exists and the rules for working within it. Read this before adding a feature or "fixing" something that looks odd — several things that look like smells are deliberate, documented below under Deferred / do not touch blindly.

---

1. Layering

Presentation   src/Screens/**, src/components/**        (UI only)
      │
Application    src/Services/**, feature hooks           (use-cases, orchestration)
      │
Domain         slices, reducers, pattern configs        (business rules, pure)
      │
Infrastructure src/core/**                              (http, storage, crypto, events)
      │
Platform       react-native, native modules

Dependencies point inward. src/core/** must never import from Screens, Services, or Redux. It reaches outward only through injection/events (see §3).

---

2. The core/ layer — the single source of infrastructure truth

Module	Responsibility	Rule
core/config/env.ts	All hosts/base URLs, selected by build type	No hardcoded URLs anywhere else.
core/http/client.ts	THE axios instance; request<T>()	Throws AppError; never returns a sentinel. All new network code uses this.
core/http/AppError.ts	Normalized typed error	Catch with isAppError(); branch on .kind.
core/observability/logger.ts	The only sanctioned log sink	Never console.* in app code. DEV-only; release-stripped.
core/observability/redact.ts	PII/secret masking	Every log payload is redacted; extend SENSITIVE_KEY_PATTERN when adding sensitive fields.
core/storage/secureStorage.ts	Keychain-backed persist storage for the auth session	Token is never in plaintext AsyncStorage.
core/events/appEvents.ts	Typed cross-layer event bus	How infra signals up without importing the store.
core/query/queryClient.ts	Module-singleton React Query client	Never construct a QueryClient in a component.
core/errors/ErrorBoundary.tsx	App-root render-error guard	Wraps the tree in App.tsx.
core/platform/polyfills.ts	Buffer / TextEncoder	Imported first in index.js; nothing may depend on load order otherwise.

---

3. Hard rules (enforced by review; some by CI)

1. Networking: use request() from core/http/client. It injects the JWT, handles 401 (emits auth/unauthorized), times out, and throws AppError. src/Axios/Axios.ts (apiCall) is a legacy compatibility adapter that preserves the old never-throws {success:false} envelope for un-migrated call sites; its contract is pinned by tests. Do not add new apiCall sites.
2. Auth token: read only via selectAuthJwt(state). The transport reads it through a provider registered in Redux/Store.ts — never import { store } into core.
3. Logout: call performLogout() from Services/Auth/session.ts. It clears redux + keychain + the query cache in one place. AuthSessionGuard (mounted in App.tsx) resets navigation to Login whenever the session ends.
4. Post-auth routing: Services/Auth/registrationRouting.ts is the single decision function. Splash and Login both call it. Do not re-implement.
5. Logging: logger.<level>(scope, message, data?). Never log key material, plaintext bids, OTPs, or full PII (the redactor is a safety net, not a licence).
6. Theme/colors: use useTheme(). Constant/Color.tsx is deprecated (see §6). There is one brand orange, sourced from theme/colors.
7. Components: one root — src/components/**. src/Component/ no longer exists.
8. Navigation: route param shapes live in src/Navigation/types.ts (RootStackParamList). NavigationString is the as const route-name registry.
9. Forward/Reverse bidding: every behavioural difference lives in Screens/Bidding/biddingPattern.ts. The screen/card contain zero if (pattern === ...).

---

4. Feature anatomy (pattern to copy)

The tender-bidding and registration features show the intended shape — logic is extracted out of the screen into pure, testable units:

Screens/Tender/tenderBidding/
  TenderBidding.tsx        presentation + state only
  envelopeTypes.ts         types
  envelopeCrypto.ts        AES/RSA (never logs key material)
  envelopePayload.ts       pure payload build + validation   ← unit-tested
  envelopeSubmission.ts    API calls
  components/*              memoized, module-scope sub-components

Screens/Ragistration/
  Ragistration.tsx         orchestration + render
  registrationState.ts     typed useReducer (was ~20 useStates) ← unit-tested
  registrationValidation.ts pure per-stage validation          ← unit-tested

When you build a feature: keep the screen thin; put decisions in pure functions; test the pure functions.

---

5. Testing & CI

• npm test (jest). 75 tests across 11 suites, concentrated on the money/crypto/auth/storage paths: envelopePayload, biddingPattern, registrationState/registrationValidation, registrationRouting, Token slice, apiCall envelope contract, AppError, redact, appEvents, and the secureStorage keychain-migration path.
• CI (.github/workflows/ci.yml) runs install → typecheck → lint → test, all blocking. tsc --noEmit is green; eslint . --quiet (errors) is green. Style warnings still exist and are being burned down; tighten to --max-warnings=0 once clean.
• New pure logic should ship with tests. UI can follow with RNTL later.

---

6. Deferred / do not touch blindly

These look like leftovers but were left deliberately. Read before "fixing".

• Constant/Color.tsx is deprecated but still imported by ~20 files for neutral grays. Its brand tokens are now sourced from the theme, but its neutral values differ from theme/colors in several places. A blind find/replace to useTheme() will change appearance — migrate screen-by-screen with visual review.
• EnvelopeCExcelPreview.tsx still uses raw axios (responseType: 'arraybuffer') and react-native-fs with 'ascii' write encoding. The RNFS → react-native-blob-util dedupe and the axios → core/http migration are deferred because this sealed-bid document flow can't be runtime-verified here and the encodings aren't 1:1. Needs a device.
• Sealed-bid crypto is AES-ECB with the symmetric key echoed to the server (randomKeyGenerated). This is a backend-contract weakness (audit §11); fixing it requires a coordinated backend change, not a client edit.
• ResetPassword sends the new password as a URL query param. Migrated to core/http (so it's redacted in logs) but the query-param placement is a backend contract — see the TODO(backend) at the call site.
• PurchaseTenderTile "details" tap navigates to 'TenderDetail', an unregistered route (a pre-existing latent bug). The intended destination is ambiguous (the tile already renders an in-tile modal), so it awaits a product decision rather than a guessed target.

---

7. Open work (gated on device or backend/ops)

• Device/emulator needed: full Auth/App two-stack navigator split (AuthSessionGuard + registrationRouting are the groundwork); release minify/shrink + App Bundle + ABI splits; verifying the Envelope C flow.
• Backend/ops needed: HTTPS for eproc-backend.lincpay (then remove its cleartext exemption in network_security_config.xml and add pinning); rotate the previously-committed keystore + Sonar token and purge git history.
• Incremental: finish Constant/Color → useTheme; per-screen typed navigation adoption (useNavigation<NativeStackNavigationProp<RootStackParamList>>); broaden accessibility labels; i18n scaffolding.