Skip to main content

Architecture Review

Documentation Audit & Code Quality Plan​

Created: April 26, 2026 Goal: Deliver a technically sound, well-documented, secure product that accurately represents what was planned and what was built — establishing a clear foundation before opening to real beta users.

Why This Matters​

The project has moved fast. M1 through M11 represents months of development, dozens of architectural decisions, production deployments, and real-world fixes. Before expanding the user base, we need to:

  1. Verify the codebase is architecturally sound and secure
  2. Ensure documentation reflects reality, not aspirations
  3. Capture everything learned so future development (and future team members) have an honest, accurate reference

Session A — M11 Housekeeping (1-2 hours)​

Goal: Close out loose ends from TRA-145 and the Playwright work.

  • TRA-171 — Fix SqlTicketNumberGenerator to seed from MAX(Number) + 1 after sequence creation
  • Fix E2E tests 03-06 state sharing — write E2E_TICKET_URL to a temp file after test 02, read it in downstream tests
  • Merge feature/TRA-145-Playwright-Tests PR → development → main
  • Merge feature/TRA-145-Playwright-Tests for API changes (GetCurrentUserEndpoint, GetCurrentTechnicianEndpoint fix)

Session B — Documentation Audit (2-4 hours)​

Goal: Produce honest, accurate documentation that reflects what was actually built. No aspirational gaps.

Input Documents to Review​

These are the original planning documents from the project files. Pete will provide them at the start of the session:

  • roundtrip-brd.docx — Business Requirements Document
  • roundtrip-prd.docx — Product Requirements Document
  • roundtrip-solution-architecture.docx — Solution Architecture Document (SAD)
  • roundtrip-api-design.docx — API Design Document
  • roundtrip-domain-model.docx — Domain Model
  • roundtrip-ddd.docx — Domain-Driven Design decisions
  • roundtrip-clean-arch.docx — Clean Architecture patterns
  • roundtrip-database-design.docx — Database design
  • roundtrip-impl-plan.docx — Implementation plan
  • roundtrip-tech-stack-analysis.docx — Tech stack decisions
  • traxs-business-plan.docx — Business plan context
  • traxs-business-case.docx — Business case

Review Approach​

For each document, evaluate:

  1. Still accurate? — Does it match what was actually built?
  2. Intentional divergence? — Did we consciously decide to do something differently?
  3. Unintentional drift? — Did we just end up somewhere different without a decision?
  4. Missing coverage? — Are there things built that the document doesn't cover at all?

Living Documents to Update​

These Linear documents need updating based on what was learned in M10/M11:

DocumentKey Updates Needed
Backend Coding Standardsresult.Type not result.ResultType; /v1/me pattern; GetCurrentTechnicianEndpoint TenantId resolution; HttpContext.Response.WriteAsJsonAsync pattern
Frontend Coding StandardsMSAL now localStorage; setAccount is async; role from /v1/me API not JWT; StatusBadge/PriorityBadge now forward ...rest props
Deployment ArchitectureADO self-hosted agent laptop in traxs-self-hosted pool; Cloudflare Pages for frontend; Secure Files → inline auth setup; repo migration from GitHub to ADO
Pre-Beta Launch ChecklistCurrent status pass — what's done, what's still open

Session C — Architecture & Security Audit (2-3 hours)​

Goal: Systematic review of both repos for security, correctness, and architectural integrity.

API (RoundTripAPI)​

Multi-tenancy audit

  • Every Dapper query has explicit AND TenantId = @TenantId — no tenant data leakage possible
  • TenantScopingBehavior correctly covers all MediatR commands and queries
  • Direct endpoint handlers (non-MediatR paths) resolve tenant correctly

Authorization audit

  • Every FastEndpoints endpoint has Roles() configured
  • Role assignments match PRD (Technician cannot call Dispatcher endpoints)
  • GET /v1/me correctly has no role restriction (any authenticated user)
  • GetCurrentTechnicianEndpoint correctly restricted to Technician role

Input validation

  • FluentValidation coverage — every command with user input has a validator
  • No unvalidated inputs reaching domain methods

Security

  • No secrets in appsettings.json or committed config files
  • No raw string interpolation in SQL (Dapper parameterization everywhere)
  • Exception middleware prevents stack traces reaching clients
  • CORS policy is appropriately restrictive for production

Ticket number sequence (TRA-171)

  • SqlTicketNumberGenerator seeds from existing max after creation

Frontend (RoundTripWeb)​

MSAL / Auth

  • localStorage MSAL cache — XSS surface acknowledged and mitigated
  • 401 responses trigger MSAL re-auth correctly
  • 403 responses handled gracefully (user sees a clear error, not a broken UI)
  • setAccount async flow — app doesn't render role-dependent UI before /v1/me resolves

API client

  • All API calls go through apiClient (no raw fetch scattered through components)
  • Error handling is consistent — TanStack Query error states used correctly

Service worker

  • Workbox guards url.origin before url.pathname (prevents intercepting cross-origin API calls)
  • Stale service worker update flow works correctly

Code quality

  • No console.log statements in production code
  • No hardcoded tenant IDs or user IDs
  • TypeScript strict mode — no any escapes

Claude Cowork — Where It Helps​

Claude Cowork (desktop automation) is best used for bounded, systematic tasks rather than open-ended review. Specific use cases:

  • Tenant scoping audit: Open RoundTripAPI, search all .cs files containing Dapper SQL for queries missing TenantId filter
  • Endpoint authorization audit: Open all *Endpoint.cs files, list each one and its Roles() configuration
  • Console.log audit: Search RoundTripWeb for console.log in non-test files
  • Hardcoded value scan: Search for known GUIDs (dev tenant, Acme tenant) in source code

These are mechanical tasks that Cowork can run systematically in minutes rather than manual file-by-file review.

Success Definition​

After all three sessions:

  1. All open M11 issues are tracked and prioritized
  2. The planning documents are annotated with what was built vs what was planned
  3. The two living coding standards documents reflect current reality
  4. The architecture and security audit is complete with findings documented
  5. Any issues found are filed as Linear tickets with appropriate priority
  6. The codebase is ready to present to beta users with confidence