Skip to content

Web Client Audit — Audit Guide

What this is: A self-contained guide for auditing the web client component of the Someli platform. Drop this file into the web client repository (alongside its source code) and follow it.

What this is for: The findings produced by following this guide will eventually be merged into a platform-level Technical Due Diligence (TDD) report. To make that merge clean, this guide enforces a specific output structure and methodology.

Independence: This guide is self-sufficient. It does not require access to the API repository's documentation tree to run the audit. References to the broader platform context are inline.

0. Quick Start

If you have one hour:

  1. Read §1 (Context) and §3 (Output Structure) — 10 minutes
  2. Run the data-collection commands in §4.1 — 15 minutes
  3. Skim the source tree to answer the 30 questions in §5 — 30 minutes
  4. Note open questions and dispatch follow-ups — 5 minutes

If you have one week (a real audit), follow the full methodology in §4–§9 and produce the full output in §3.

1. Context

1.1 What you are auditing

The Someli web client is the customer-facing user interface of the Someli platform. The platform is a B2B SaaS for AI-driven social media content management — users upload brand assets, the platform generates social media posts via AI, users approve and schedule them across multiple social platforms.

The web client is one of three components that together make up the platform:

Component Audit status (at the time you read this)
someli-api (backend HTTP API + ~108 background workers) ✅ Audited
Web Client (this audit) ⏳ This is what you're producing
Admin Dashboard (internal staff UI) ⏳ Pending

The backend is a Node.js + MySQL application with ~728 REST endpoints and 49,422 lines of route handlers across two monolithic route files. It has significant accumulated technical debt (the audit has been candid about this). Treat the backend as a known quantity, not an aspirational target.

1.2 Why this audit is happening

The audit feeds into a master Technical Due Diligence (TDD) report that will be:

  • Read by the engineering leadership / CTO
  • Read by board members and prospective investors
  • Submitted to enterprise customers as part of their procurement security review
  • Referenced in eventual SOC 2 Type I / ISO 27001 / GDPR readiness work
  • Used as the technical due-diligence baseline by an acquirer or strategic partner

The TDD report's quality depends on the per-component audits being comprehensive, accurate, and consistently structured. This guide enforces structure so the eventual platform-level synthesis is straightforward.

1.3 What good looks like

A successful audit produces:

  1. A comprehensive component documentation tree (per §3) that an external reader could use to understand the web client without reading the source code
  2. A clear list of findings with severity ratings and remediation paths
  3. A maturity assessment using the 14-pillar CMMI 1–5 model (per §6)
  4. A risk register for component-specific risks
  5. A roadmap for component-specific improvements, sequenced into phases
  6. A verification report confirming that the documentation matches the codebase
  7. Findings that integrate cleanly into the master TDD (per §9)

Output should be honest about gaps. The backend audit found and documented 5 critical issues, 14 drifts between docs and reality, and ~30 strategic recommendations. Expect a similar profile here. Quality of the audit is judged by what it surfaces, not by how positive it sounds.

2. Methodology

The methodology mirrors what was used on the backend:

2.1 Phases

Phase Goal Output
Phase A — Inventory Catalog what exists Per-domain documents listing routes, components, dependencies, integrations
Phase B — Subsystem deep-dives Document how subsystems work Architecture, auth-client, API-consumption, build, observability docs
Phase C — Cross-cutting findings Identify platform-level concerns Security, performance, accessibility, error handling docs
Phase D — Strategic synthesis Produce the readiness assessment enterprise-readiness.md per §7
Phase E — Verification Confirm docs match reality verification-report.md per §8
Phase F — Integration Feed findings into the master TDD Component summaries per §9

2.2 Order matters

Phase A must complete before Phase B; B before C; C before D. Phase E happens after D, then loops back to fix any drift. Phase F happens after E completes.

The single most common failure mode of audits like this is trying to write the strategic synthesis before the inventory is complete. The synthesis will be wrong if the inventory is wrong. Resist the temptation to skip ahead.

2.3 Honesty principles

  • Cite sources for every claim. A claim of "uses React 18" should reference package.json:line or similar.
  • Mark uncertain claims [VERIFY]. Anything not directly verifiable from the code goes in a tracking list.
  • Document what's missing. "No accessibility testing exists" is a finding. "Accessibility not assessed" is a doc gap.
  • Don't invent maturity. If a practice doesn't exist, the rating is 1, not "we plan to."
  • Number all findings for traceability into the master TDD.

3. Output Structure

The audit produces a documentation subtree shaped exactly like the backend's. This consistency is what makes platform-level synthesis tractable.

3.1 Files to produce

web-client/
├── README.md                            # Component-level index
├── architecture-overview.md             # Frontend architecture and tech stack
├── routing-and-state.md                 # SPA routing, state management
├── api-consumption.md                   # How the client talks to the backend API
├── authentication-client.md             # Token storage, refresh, session handling
├── ui-component-library.md              # Design system, component inventory
├── accessibility.md                     # WCAG posture
├── performance.md                       # Bundle, Core Web Vitals
├── security.md                          # CSP, XSS, dependency CVEs
├── testing.md                           # Unit / integration / e2e
├── build-and-deploy.md                  # Bundler, CDN, deployment
├── observability.md                     # Sentry, RUM, analytics
├── i18n.md                              # Internationalization (or note absence)
├── seo-and-metadata.md                  # SEO, OG tags, structured data
├── dependencies-inventory.md            # All npm packages with usage / status
├── verification-report.md               # Quantitative + control-flow audit
├── enterprise-readiness.md              # Maturity model + roadmap + risk register
├── verify-markers.md                    # Open questions / [VERIFY] tracker
└── visuals-tracking.md                  # Suggested diagrams (optional)

Each file's expected content is templated in §10.

3.2 Naming conventions

  • All filenames are kebab-case (api-consumption.md, not apiConsumption.md)
  • All files use .md extension
  • README.md is the entry point — every other doc is linked from it
  • Filenames match those in the API subtree where the topic is the same (e.g., dependencies-inventory.md exists in both)

3.3 Linking discipline

  • Internal links use relative paths within the subtree (./architecture-overview.md, not absolute paths)
  • Cross-component links go through the master document layer when the platform-level docs are eventually authored — for now, just note "see backend authentication.md for the API side of this contract"
  • External links (to libraries, standards, RFCs) are fine but use stable URLs

4. Phase A — Inventory

The first task is to catalog what's in the repository. Run these commands (or AI-assisted equivalents) and capture the output.

4.1 Data-collection commands

# Repository basics
ls -la
cat README.md  # if any

# Tech stack
cat package.json | jq '{name, version, engines, scripts, type, dependencies, devDependencies}'

# Bundle / build configuration
ls -la *.config.js *.config.ts *.config.mjs vite.config.* webpack.config.* next.config.* nuxt.config.* 2>/dev/null
ls .babelrc* tsconfig*.json 2>/dev/null

# Source structure
find src -type d | head -40
find src -type f -name '*.tsx' -o -name '*.ts' -o -name '*.jsx' -o -name '*.js' | wc -l
find src -type f -name '*.tsx' -o -name '*.ts' -o -name '*.jsx' -o -name '*.js' | xargs wc -l 2>/dev/null | tail -1

# Tests
find . -path ./node_modules -prune -o -name '*.test.*' -print -o -name '*.spec.*' -print 2>/dev/null | wc -l
find . -path ./node_modules -prune -o -name 'cypress' -print -o -name 'playwright' -print -o -name 'e2e' -print 2>/dev/null | head

# Public / static
ls public/ static/ 2>/dev/null

# CI / deploy
cat .github/workflows/*.yml 2>/dev/null
ls .gitlab-ci.yml Jenkinsfile vercel.json netlify.toml 2>/dev/null

# Env vars referenced (frontend-specific patterns)
grep -roE 'import\.meta\.env\.[A-Z_]+|process\.env\.[A-Z_]+|VITE_[A-Z_]+|REACT_APP_[A-Z_]+|NEXT_PUBLIC_[A-Z_]+' src 2>/dev/null | awk -F. '{print $NF}' | sort -u

# Routes (depends on framework — common patterns)
grep -rEn "<Route\b|createBrowserRouter|createRouter|definePage|router\.addRoute" src 2>/dev/null | head -30

# API call sites (look for fetch / axios / etc.)
grep -rEn "axios\.|fetch\(|useFetch\(|useQuery\(|apiClient\." src 2>/dev/null | wc -l

# Auth-related code (token storage)
grep -rEn "localStorage|sessionStorage|document\.cookie|setCookie|getCookie" src 2>/dev/null | head -20

# Bundle / deps weight
du -sh node_modules 2>/dev/null
du -sh dist build .next .nuxt out 2>/dev/null | head

4.2 What to record

For each command's output, capture into the relevant target document:

Command output Target document
package.json summary architecture-overview.md, dependencies-inventory.md
Build config files build-and-deploy.md
src/ structure architecture-overview.md
Test discovery testing.md
CI / deploy files build-and-deploy.md
Env-var inventory architecture-overview.md (consider a separate configuration.md if many)
Route inventory routing-and-state.md
API call site count api-consumption.md
Token-storage patterns authentication-client.md, security.md
Bundle sizes performance.md

4.3 Inventory output: the catalog

By end of Phase A, produce first drafts of these files:

  • architecture-overview.md — at minimum: framework, version, build tool, routing approach, state management approach
  • dependencies-inventory.md — at minimum: complete list of dependencies with versions
  • routing-and-state.md — at minimum: list of routes and the state-management library in use

These become the foundation for Phases B–D.

5. Phase B — Subsystem Deep-Dives

For each subsystem, answer the questions in this section. Findings populate the corresponding document.

5.1 Architecture (architecture-overview.md)

  1. Framework and version? (React 18 / Vue 3 / Angular 17 / Svelte 4 / Next.js / Nuxt / etc.) Cite package.json.
  2. Build tool? (Webpack / Vite / Rollup / Turbopack / Bun) — version and config approach.
  3. Module system? (ESM / CJS / mixed) Cite tsconfig.json or package.json:type.
  4. TypeScript or JavaScript? If TS, is strict: true? Verify in tsconfig.json.
  5. Source structure — is it organized by feature, by type, by layer? List the top-level directories under src/ with one-line descriptions of each.
  6. Component tree depth — how deeply nested is the typical component? Pick a complex page and show its tree.
  7. Code style enforcement — ESLint? Prettier? Stylelint? Pre-commit hooks?
  8. Largest files — find src -type f \( -name "*.tsx" -o -name "*.ts" -o -name "*.jsx" -o -name "*.js" \) -exec wc -l {} \; | sort -rn | head -20. Are any files over 500 lines? Over 1000? (Mirror the backend's "21k-line file" finding if it applies.)
  9. Dead code — any commented-out blocks larger than 20 lines? Any _old.tsx / .bak.ts patterns?
  10. Build process — what does npm run build produce? What's in the output directory?

5.2 Routing & State (routing-and-state.md)

  1. Routing library? (react-router / vue-router / Next.js routing / file-based / TanStack Router)
  2. Total number of routes — list them all with auth requirement (public / authenticated / admin)
  3. Deep linking — does it work? Are there routes that lose state on refresh?
  4. Code splitting — is it route-based? Component-based? Manual chunks? Cite the build config.
  5. State management library? (Redux / Zustand / MobX / Recoil / Jotai / Pinia / Vuex / Context / SWR / TanStack Query)
  6. Global state shape — what's stored at the root? User session, brand profile, schedule data, etc.?
  7. Persistence — does state persist across reloads? In what storage? Watch for tokens in local state — cross-reference §5.4.
  8. Error boundaries — are React error boundaries (or framework equivalent) wrapping the app?

5.3 API Consumption (api-consumption.md)

  1. HTTP client? (axios / fetch / ky / native + wrapper / TanStack Query / RTK Query)
  2. Wrapper layer — is there a single API client module, or are calls scattered? List the locations.
  3. Base URL configuration — env var? hardcoded? per-environment?
  4. Authentication header — what header name does the client send? Does it match TOKEN_HEADER_KEY from the backend?
  5. Token attachment — is auth automatic via interceptor, or per-call?
  6. Token refresh — how is it handled? On 401 response? Proactively before expiry? Not at all?
  7. Error handling — is there a single error handler? Toast notifications? Re-throw to component?
  8. Retries — are network errors retried? With backoff?
  9. Request cancellation — does the client cancel in-flight requests on unmount / route change?
  10. Endpoints used — list which backend endpoints are exercised. Cross-reference backend's API inventory if available.
  11. Response shape handling — backend has inconsistent response shapes (envelope vs raw vs string). How does the client cope?

5.4 Authentication (Client-side) (authentication-client.md)

  1. Where is the token stored? localStorage / sessionStorage / httpOnly cookie / in-memory only / IndexedDB?
  2. What's the security implication? localStorage is XSS-readable; httpOnly cookie is not. Is the choice deliberate?
  3. Login flow — POST /auth/login (backend); what does the client do with the response?
  4. OAuth flow — does the client kick off OAuth, or does the backend handle redirects?
  5. Logout — is the token cleared client-side? Is there a server-side revocation call?
  6. Token expiry handling — does the client detect expiry and prompt re-login, or wait for a 401?
  7. MFA / 2FA — is it supported? What's the flow?
  8. Session persistence — does "remember me" exist? How does it differ from default?
  9. Multi-tab synchronization — if a user logs out in one tab, do other tabs handle it (storage events)?
  10. CSRF protection — if the client uses cookies, is there a CSRF token? How is it set?

5.5 UI Component Library (ui-component-library.md)

  1. Design system in use? (Material-UI / Ant Design / Chakra / shadcn/ui / Tailwind UI / custom)
  2. CSS approach? (Tailwind / CSS Modules / styled-components / emotion / SCSS / vanilla CSS)
  3. Internal component library — is there a src/components/ with reusable primitives? List the top 20 primitives.
  4. Component count — total components in the codebase. find src/components -type f | wc -l
  5. Pattern consistency — pick 5 forms in the app. Do they use the same form-handling library? Same validation patterns?
  6. Theming — light/dark mode? Brand-color customization?
  7. Storybook or similar — is there a component-development sandbox?

5.6 Accessibility (accessibility.md)

  1. WCAG compliance level claimed? (A / AA / AAA / unstated)
  2. Automated checks — is eslint-plugin-jsx-a11y (or framework equivalent) configured? What's the rule severity?
  3. Manual testing — has the team done keyboard-only testing? Screen-reader testing? Documented?
  4. Color contrast — is contrast tested? Tooling? Failing combinations?
  5. Focus management — do modals trap focus? Do route changes shift focus? Is there a "skip to content" link?
  6. Semantic HTML — is the markup semantically correct, or div-soup?
  7. ARIA usage — is ARIA used correctly, or as a band-aid?
  8. Form labels — are inputs properly labeled?
  9. Image alt text — are images required to have alt text? Is this enforced?
  10. Known accessibility issues — any open tickets / known bugs?

5.7 Performance (performance.md)

  1. Initial bundle size — gzipped main chunk size. Run npm run build and inspect.
  2. Total JS shipped on first page load — including async chunks if route-loaded.
  3. Largest dependency contributions — use bundlephobia or webpack-bundle-analyzer. Top 5 heaviest deps.
  4. Code splitting — route-based? Component-based? React.lazy / defineAsyncComponent / loading() patterns?
  5. Tree shaking — is the build tool configured for it? Are there imports defeating it (import * as)?
  6. Image optimization — Next/Image / NuxtImage / vanilla <img>? CDN serving WebP/AVIF?
  7. Font loading — font-display: swap? Self-hosted? Google Fonts?
  8. Core Web Vitals — has the team measured? LCP / FID / CLS / INP. Any RUM data?
  9. Caching strategy — service worker? Cache-Control headers? CDN?
  10. Render performance — any virtualized lists for long content? Memoization patterns?

5.8 Security (security.md)

  1. Content Security Policy (CSP) — is one set? Read the headers (curl -I) on a deployed page. unsafe-inline / unsafe-eval?
  2. Subresource Integrity (SRI) — are 3rd-party scripts SRI-protected?
  3. dangerouslySetInnerHTML — count instances; review each for sanitization.
  4. eval / new Function — count instances; are they justified?
  5. Token in URL — does the client ever put the token in URL params? Logged in browser history / referer.
  6. Hardcoded secrets — run gitleaks over the repo. What's found?
  7. Public env vars — Vite's VITE_* / Next's NEXT_PUBLIC_* are baked into the bundle. Are any sensitive?
  8. Dependency CVEs — yarn audit / npm audit. Critical / High count?
  9. Dependabot / Snyk in CI?
  10. CORS — is the client served from the same origin as the API, or different? CORS implications?
  11. Mixed content — any http:// URLs in production?
  12. Click-jacking — X-Frame-Options / frame-ancestors set?
  13. Auth-related XSS — if the token is in localStorage, what's the XSS exposure surface?

5.9 Testing (testing.md)

  1. Test framework? (Jest / Vitest / Mocha / Karma / Cypress / Playwright)
  2. Unit test count — find . -name '*.test.*' -o -name '*.spec.*' | wc -l
  3. Integration test count
  4. E2E test count — list the user journeys covered.
  5. Code coverage — if measured, what's the percentage? Is there a gate?
  6. Visual regression testing — Chromatic / Percy / Loki?
  7. Cross-browser testing — manual? BrowserStack? Playwright multi-browser?
  8. CI test execution — do tests run on every PR? Time to run?
  9. Flaky test handling — known flaky tests? Quarantined?
  10. Mock strategy — how is the API mocked in tests? MSW? jest.mock? Test fixtures?

5.10 Build & Deploy (build-and-deploy.md)

  1. Build tool and version (cited from package.json)
  2. Build command — npm run build does what?
  3. Build time — typical local build time on a developer machine?
  4. Build artifact — directory? Size?
  5. Source maps — generated? Included in production? (Risk: leaks code.)
  6. Deployment target — Vercel / Netlify / AWS S3+CloudFront / custom?
  7. Hosting platform configuration — vercel.json / netlify.toml / cloudfront-config.json / etc.?
  8. CI/CD pipeline — list the workflows. What runs on push? On PR?
  9. Preview deployments — does each PR get a preview URL?
  10. Rollback mechanism — how is a bad deploy reverted?
  11. Environment configuration — how do dev / staging / prod differ? Env-var management?
  12. CDN configuration — cache headers? Invalidation strategy?

5.11 Observability (observability.md)

  1. Error tracking — Sentry / Bugsnag / Rollbar / nothing?
  2. Real User Monitoring (RUM) — Sentry RUM / Datadog RUM / SpeedCurve / nothing?
  3. Analytics — Google Analytics / Mixpanel / Amplitude / Segment / Plausible / nothing?
  4. Console logging — is there logging in production code? (Equivalent to backend's console.log finding.)
  5. Source-map upload — does CI upload source maps to the error-tracking service?
  6. User session replay — Sentry / FullStory / LogRocket?
  7. Performance monitoring — Web Vitals reported anywhere?
  8. Error boundary handling — is the error reported to tracking, or just shown to user?
  9. Feature flag system — LaunchDarkly / Statsig / Flagsmith / homegrown / none?

5.12 i18n / Localization (i18n.md)

  1. Library? (i18next / react-intl / vue-i18n / lingui / nothing)
  2. Languages supported — list them.
  3. Translation source — JSON files in repo? Translation management system (TMS)?
  4. Coverage — do all UI strings flow through the i18n layer, or are there hardcoded strings?
  5. Pluralization / formatting — handled correctly per locale?
  6. RTL languages — Arabic / Hebrew / etc.? CSS / layout impact?
  7. Date / number / currency formatting — locale-aware?

5.13 SEO & Metadata (seo-and-metadata.md)

  1. SSR / SSG / SPA — what's the rendering model? (Affects SEO heavily.)
  2. Meta tags — title / description / OG / Twitter Card per page?
  3. Structured data — JSON-LD?
  4. Sitemap — generated?
  5. robots.txt — appropriate?
  6. Canonical URLs — set per page?
  7. 404 handling — proper HTTP 404, not 200 with error content?

6. Phase C — Cross-Cutting Findings + Maturity

6.1 Maturity assessment

Use the same 14-pillar CMMI 1–5 model as the backend audit. You apply this to the web client, not the platform. Platform-level rating happens in the master TDD by taking the worst-of-components per pillar.

For each pillar, rate the web client current state on the 1–5 scale below and propose a 12-month target.

The 5 levels:

Level CMMI name Plain reading
1 Initial Ad-hoc, heroic, undocumented, single point of human failure
2 Repeatable / Managed Same person can do it twice; partly documented
3 Defined Codified, anyone on the team can do it, low truck-factor risk
4 Quantitatively Managed Instrumented, measured, bounded by SLOs / coverage thresholds
5 Optimizing Continuous-improvement loop, automated remediation

The 14 pillars (apply each to the web client):

Pillar Web-client lens
Architecture & Modularity File / component / module organization; max file size; lint enforcement
API Contract & Versioning Does the client consume a versioned API contract? OpenAPI types generated?
Data Architecture State management discipline; persistence approach; cache invalidation
Background Processing Service worker / Web Workers / async patterns
Security & Compliance CSP, XSS, deps, auth client posture
Observability Error tracking, RUM, analytics, source maps
Reliability & Resilience Error boundaries, offline handling, retry logic
Scalability Bundle size, code-splitting, performance under load
Testing & Quality Gates Unit / integration / e2e coverage; CI gates
CI/CD & Deployment Pipeline maturity, preview deploys, rollback
Infrastructure as Code Hosting config, CDN config in code
Cost Visibility & FinOps CDN egress, RUM data costs, third-party costs visible?
Documentation & Knowledge Management Internal docs, component docs, ADRs
Team Practices & Governance PR reviews, code-review checklist, postmortems

Output: a maturity table in enterprise-readiness.md.

6.2 Cross-cutting risks

After deep-dives complete, identify cross-cutting risks. These are risks that span subsystems or have platform-level implications. Examples:

  • "Token in localStorage means any XSS = full account takeover"
  • "No source-map upload to error tracker means production errors are unreadable"
  • "Bundle is 3 MB gzipped — Lighthouse performance score < 50"
  • "No automated accessibility testing — WCAG compliance unverifiable"
  • "Public env var includes API key for [vendor X]"

Add these to enterprise-readiness.md § Risk Register.

6.3 Strategic recommendations

For each significant finding, propose a remediation. Categorize:

  • Phase 0a — This week: Trivial high-impact fixes (e.g., upgrade vulnerable packages with known patches; turn on a CI gate)
  • Phase 0 — Stabilize (months 0–3): Security hygiene; basic observability; testing infrastructure
  • Phase 1 — Foundation (months 3–9): TypeScript adoption; design system consolidation; performance optimization
  • Phase 2 — Modular Refactor (months 9–18): Component-library refactor; state-management consolidation
  • Phase 3 — Selective Extraction (months 18+): Optional; trigger-driven

Output: a roadmap table in enterprise-readiness.md.

7. Phase D — enterprise-readiness.md

This is the strategic deliverable. Structure:

# Web Client — Enterprise Readiness Assessment

## 1. Executive Summary
- Verdict (1 paragraph)
- Top 3 strengths
- Top 5 risks
- Top 5 recommendations

## 2. Methodology & Scope
- Frameworks used
- Source documents
- What was audited / what was not

## 3. Maturity Assessment
- 14-pillar table: current / 12-mo target / 24-mo target
- Per-pillar narrative

## 4. Findings (by pillar or by subsystem)
- Each finding with severity, evidence, mitigation phase

## 5. Strategic Decisions
- Framework / runtime decisions
- Bundling / build tool decisions
- State management strategy
- Component library strategy

## 6. Roadmap
- Phase 0a / 0 / 1 / 2 / 3
- Effort estimates per item

## 7. Risk Register
- Per-risk: ID, description, likelihood, impact, mitigation phase
- Tag platform-level risks with [ALL] for the master TDD

## 8. Standards Compliance
- WCAG (accessibility)
- OWASP Top 10 (web app security)
- Core Web Vitals targets

## 9. Open Questions
- [VERIFY] markers for follow-up

This document mirrors the backend's enterprise-readiness.md and is the input for the master TDD's §5.2 Web Client section.

8. Phase E — Verification

Before the audit is "done," produce a verification report that confirms the documentation matches reality.

8.1 Quantitative checks

For every numeric claim in the docs, re-run the underlying command and confirm. Examples:

  • "Bundle is 412 KB gzipped" → du -sh dist/assets/*.js | head and verify
  • "94 dependencies" → jq '.dependencies | length' package.json and verify
  • "47 routes" → recount <Route> declarations in source

Produce a verification-report.md listing: - Claims verified ✅ - Claims that drifted 🔧 (with the corrected number) - Claims that need follow-up ⚠

8.2 Control-flow / narrative checks

For narrative claims (e.g., "the client sends Authorization: Bearer <token> on every authenticated request"), trace the actual code and confirm. Examples:

  • "Token refresh on 401" → find the axios interceptor / equivalent; confirm the behavior
  • "Service worker caches assets" → find the SW registration; confirm what it caches
  • "Forms use Zod for validation" → spot-check 5 forms

Document any drift in the same verification-report.md.

8.3 Apply the corrections

If verification finds drift, fix the docs in the same PR as the verification report. The doc tree should be accurate by the end of Phase E.

9. Phase F — Integration into the Master TDD

Once Phases A–E are complete, the audit findings need to feed into the platform-level master TDD report.

9.1 Hand-off package

The audit output (the web-client/ documentation subtree) is delivered as a complete, self-contained directory. Its contents:

File Purpose for the master TDD
README.md Component-level index
architecture-overview.md Source for master § 3.2 (Tech stack per component)
enterprise-readiness.md Source for master § 5.2 (Web Client summary), § 6 (Risk Register), § 7 (Roadmap)
security.md Source for master § 4.1 (Security cross-cutting)
observability.md Source for master § 4.2 (Observability cross-cutting)
authentication-client.md Source for master § 4.4 (Identity end-to-end)
verification-report.md Source for master § 9 (Audit trail)
Other detail docs Appendix B references

9.2 Integration steps for the master TDD author

When integrating these findings into the master TDD:

  1. Read the component's enterprise-readiness.md § Executive Summary — the verdict goes into master § 1 with appropriate caveats
  2. Read the component's maturity ratings — the platform-level rating is the worst-of-components per pillar
  3. Read the component's risk register — append risks to master § 6 with [WC] tags
  4. Read the component's roadmap — append items to master § 7 with [WC] tags
  5. Cross-reference the security findings — combine with backend findings; reconcile (e.g., "backend issues plaintext login token + frontend stores it in localStorage = double exposure")
  6. Cross-reference the auth findings — produce the end-to-end identity flow narrative for master § 4.4
  7. Update master § 5.2 with the web-client component summary
  8. Bump the master TDD version — v0.1 → v0.2

The master TDD is at <platform-doc-tree>/tdd-report.md. The author of that update has the platform-level context and is responsible for the synthesis. Your job is to deliver the complete, accurate component subtree — they take it from there.

10. Document Templates

Use these as starting skeletons. Fill in evidence-cited content per §4–§5.

10.1 README.md template

# Web Client — Component Documentation

This is the documentation subtree for the Someli platform's customer-facing web client.

## Index

### Architecture & Code Organization
- [Architecture Overview](./architecture-overview.md)
- [Routing & State Management](./routing-and-state.md)
- [UI Component Library](./ui-component-library.md)
- [i18n](./i18n.md)
- [SEO & Metadata](./seo-and-metadata.md)

### Behavior & Integration
- [API Consumption](./api-consumption.md)
- [Authentication (Client-side)](./authentication-client.md)

### Cross-Cutting Concerns
- [Performance](./performance.md)
- [Accessibility](./accessibility.md)
- [Security](./security.md)
- [Observability](./observability.md)
- [Testing](./testing.md)

### Operations
- [Build & Deploy](./build-and-deploy.md)
- [Dependencies Inventory](./dependencies-inventory.md)

### Strategy
- [Enterprise Readiness](./enterprise-readiness.md)

### Audit Trail
- [Verification Report](./verification-report.md)
- [Verify Markers](./verify-markers.md)

---

## Component Summary

| | |
|--|--|
| Component name | Web Client |
| Purpose | Customer-facing UI for Someli platform |
| Tech stack | (to be populated from architecture-overview.md) |
| Audit version | 0.1 |
| Last verified | YYYY-MM-DD |

10.2 verification-report.md template

# Web Client — Verification Report

Audit of quantitative and narrative claims in the web-client documentation subtree against the actual codebase.

## Summary

| Category | Count |
|----------|------:|
| Claims verified ✅ | TBD |
| Claims with drift 🔧 | TBD |
| Claims requiring follow-up ⚠ | TBD |

## A. Verified Claims

| Claim | Where claimed | Reality |
|-------|---------------|---------|
| (e.g.) Uses React 18.2.0 | `architecture-overview.md` | ✅ confirmed in `package.json` |

## B. Drifted Claims

| Drift | Recommended fix |
|-------|-----------------|
| (e.g.) Doc says 94 deps; actual is 97 | Update `dependencies-inventory.md` § At a Glance |

## C. Follow-up Needed

| Item | Why deferred |
|------|--------------|
| (e.g.) Production CSP header | Need to access deployed site to verify; doc claim is inferred from build config |

10.3 enterprise-readiness.md template

(See §7 above for full structure.)

11. Quality Bar

The audit is "done" when:

  • Every file in §3.1 exists and has content
  • Every claim in every doc cites a source (file:line, command output, or external standard)
  • verification-report.md exists and shows zero unaddressed drifts
  • verify-markers.md lists all open questions with owners
  • enterprise-readiness.md § Executive Summary reads cleanly to a non-engineer
  • At least one cross-cutting integration insight is identified (e.g., backend + frontend security combine in some way the master TDD must address)

12. Pitfalls to Avoid

These are the failure modes seen in similar audits:

  1. Skipping Phase A. Without a proper inventory, the deep-dives miss things. Spend the time.
  2. "Looks fine to me" claims without sourcing. Cite or don't claim.
  3. Hiding bad news. The audit's value is what it surfaces. Politeness damages credibility.
  4. Using superlatives. "Excellent" / "fragile" / "amazing" — replace with cite-able assertions.
  5. Inventing maturity. If a practice doesn't exist, the rating is 1, not "we're working on it."
  6. Comparing to backend. Don't. The web client is its own component; rate it on its own merits.
  7. Forgetting to integrate. Phase F is the deliverable; the docs are inputs.
  8. Letting the audit drift. When the codebase changes, the docs must be re-verified. Set a re-audit cadence (every 6 months recommended).

13. Estimated Effort

Audit depth Effort (one experienced auditor)
Surface — inventory only (Phase A) 1–2 days
Standard — inventory + deep-dives (Phases A–B) 3–5 days
Full — all phases including verification (Phases A–E) 5–10 days
Full + integration into master TDD (Phases A–F) 7–14 days

For a typical web client of moderate size (~50 routes, ~400 components, ~200 dependencies), expect 7–10 working days for a thorough audit by one experienced auditor with appropriate codebase access.

If you have AI assistance (Claude, GPT-4, or similar), expect to compress to 3–5 working days for a thorough audit, with the human reviewing AI-generated drafts and probing follow-up questions.

14. Frameworks Cited

The audit references these external frameworks. They don't need to be re-authored — just point at them when relevant:

  • OWASP Top 10 (2021) — web application security risks
  • OWASP ASVS — application security verification standard
  • WCAG 2.1 AA — accessibility minimum target
  • Core Web Vitals (Google) — performance metrics
  • Twelve-Factor App — operational hygiene
  • CMMI 1–5 — maturity scale
  • ISO/IEC 25010 — software quality model
  • NIST CSF — cybersecurity risk-framing

When citing a finding, anchor it to one of these (e.g., "this is OWASP A03 — Injection").

15. Where to Send Questions

If something in this guide is unclear or doesn't fit your context:

  1. Check the equivalent backend doc for an example of the pattern (the master TDD report's Appendix A points at all backend docs)
  2. If still unclear, raise it with the engineering lead

The master TDD report (tdd-report.md in the platform doc tree) is the integration target — when in doubt, "does this finding affect what the TDD says?" is a useful framing.

16. Final Note

This audit guide is itself a deliverable — it can be improved over time. If you find a category that's missing, a question that's poorly framed, or a template that's unhelpful, fix it in this file. The next auditor (whether for this component again or for a different component) will benefit.

When the platform's third component (admin dashboard) is audited, this guide is the starting point — adapted with admin-specific concerns (RBAC, audit logging, sensitive-data handling, MFA, etc.). The structure should remain consistent.

End of guide.