proposal-system/CLAUDE.md

# Proposal System - Claude Code Project Memory

## Project Overview

Proposal management platform for Sea Haven Industries. Dispatchers submit service requests, AI generates draft line items via Bedrock RAG, admins review/approve in a pricing workspace, system produces branded PDFs.

## Architecture

- **api/**: .NET 8 API, EF Core, PostgreSQL (Aurora Serverless v2), Cognito JWT auth
- **web/**: React 19 + MUI v9 SPA, Vite, CloudFront + S3
- **mobile/**: React Native 0.86 iOS app, offline-capable, Hermes
- **lambdas/**: Python 3.12 Lambdas (ARM64): pdf-extract, pdf-generate, library-ingest, suggestions, aurora-pgvector-init
- **infra/**: CDK TypeScript (foundation-stack, compute-stack, frontend-stack)
- **shared/**: Shared TypeScript API contracts
- **scripts/**: Local dev helpers

## Auth Model

External: Cognito JWT via API Gateway (web + mobile client IDs, groups: dispatchers/admins/sysadmins)
Internal: Lambdas → .NET Function URL with Secrets Manager API key via custom middleware

## Key Decisions (ADRs in docs/adr/)

- **ADR 0001**: Bedrock KB vector store is Aurora PostgreSQL + pgvector (replaced OpenSearch Serverless; `oss-index-creator` Lambda replaced by `aurora-pgvector-init`)
- **ADR 0002**: SHOC merge boundary — backends stay separate services permanently (PostgreSQL + Cognito here; SQL Server + ASP.NET Identity in SHOC); consolidation converges on conventions/layers/service patterns, never on platform
- **ADR 0003**: SHOC dev's design system + UI/UX layout is canonical (Montserrat/DM Sans, primary #1c75bc, 244px sidebar, CSS-variable single-token-source consumed by MUI via getCssVar); the old Nunito/#0c4f6f canon and the interim "Sea Haven Ops" Inter/#2563EB theme are superseded

## Request Flow

1. Dispatcher submits proposal (web/mobile) → InReview (no Draft stage)
2. Bedrock RAG suggests line items from pricing library
3. Admin reviews in workspace, edits line items, approves
4. PDF generation queued via SQS → Python Lambda → branded PDF → S3
5. State machine: InReview → Approved → Sent → Revised

## Infrastructure

Deploys to the **seahaven-prod** account (`011934824531`), us-east-1. (mgmt `328440206208` is frozen for workloads; staging is hard-disabled in `infra/lib/config.ts` until retargeted to seahaven-dev `710827005802`.) Aurora PostgreSQL 15 Serverless v2 (RDS Data API + pgvector), S3, SQS+DLQ, Cognito+Google OAuth, Bedrock KB (Aurora pgvector store — ADR 0001), GitHub Actions OIDC, CloudFront+S3 OAC. Prod deploys run via the `deploy.yaml` pipeline (workflow_dispatch) only — no local `cdk deploy` to prod.

## Working Rules

- Never commit secrets, credentials, .env files, or local artifacts
- If secrets found in code: document, remove safely, ensure proper config mechanism
- Preserve existing business logic unless broken, insecure, or contradicted
- Run lint/typecheck/build/test after each phase

## Finding-ID Convention

Code comments and commit messages reference finding IDs from a prior security-audit remediation (e.g. `API-C1`, `WEB-H3`, `LAM-H4`). These IDs are embedded directly in the codebase, so keep the convention documented:

- Reference finding IDs in commit messages and code comments
- Format: `// Fix: API-C1 — scope internal key to /internal/ paths`
audit: fix all Critical and High security/reliability issues across monorepo 6-domain audit (API, web, mobile, lambdas, infra, QA) with fixes: API security: scope internal API key middleware to allowed paths only, return 401 on invalid key instead of falling through, remove unvalidated JWT code path, sanitize error messages, add UpdateProposal validator, remove status field from UpdateProposalRequest to prevent over-posting, log swallowed exceptions in ProposalService. Infrastructure: enforce SSL on all S3 buckets, encrypt SQS queues, enable optional MFA on Cognito, add API Gateway access logging. Lambdas: fix _retry_request undefined variable across all 4 Lambdas, re-raise exceptions in pdf-extract/pdf-generate instead of swallowing, add idempotency guard to suggestions Lambda. Web: add ErrorBoundary, add auth loading state to ProtectedRoute, add mutation error toasts in AdminWorkspace, fix dead Cognito link. Mobile: add mutex to offline queue processing, distinguish permanent vs retryable failures, register all screens for both roles, log sync errors. Swagger/OpenAPI: add Swashbuckle with JWT bearer security definition, add ProducesResponseType attributes to key endpoints. Includes AUDIT-REPORT.md with complete findings and CLAUDE.md project instructions. 2026-05-27 15:33:27 -04:00			`# Proposal System - Claude Code Project Memory`

			`## Project Overview`

			`Proposal management platform for Sea Haven Industries. Dispatchers submit service requests, AI generates draft line items via Bedrock RAG, admins review/approve in a pricing workspace, system produces branded PDFs.`

			`## Architecture`

docs: SHOC-alignment Phase 1 — ADRs, governance files, doc corrections (#220) - Add ADR 0002 (SHOC merge boundary: separate backend services, shared conventions) and ADR 0003 (adopt SHOC design system + UI/UX layout) - Add CODEOWNERS (internal-dev) and PR template (Summary/Test plan/Jira/ docs-current checklist + contract-table convention) - Fix stale facts in README/CLAUDE.md: MUI v7→v9, RN 0.85→0.86, OpenSearch Serverless/oss-index-creator → Aurora pgvector/ aurora-pgvector-init (ADR 0001), test counts 149→186 (123 xUnit / 26 vitest / 37 pytest), deploy triggers are workflow_dispatch-only, reusable workflow refs float on @main, aws-cdk-lib version claim replaced with Dependabot-maintained note 2026-07-13 17:00:45 -04:00			`- api/: .NET 8 API, EF Core, PostgreSQL (Aurora Serverless v2), Cognito JWT auth`
			`- web/: React 19 + MUI v9 SPA, Vite, CloudFront + S3`
			`- mobile/: React Native 0.86 iOS app, offline-capable, Hermes`
			`- lambdas/: Python 3.12 Lambdas (ARM64): pdf-extract, pdf-generate, library-ingest, suggestions, aurora-pgvector-init`
audit: fix all Critical and High security/reliability issues across monorepo 6-domain audit (API, web, mobile, lambdas, infra, QA) with fixes: API security: scope internal API key middleware to allowed paths only, return 401 on invalid key instead of falling through, remove unvalidated JWT code path, sanitize error messages, add UpdateProposal validator, remove status field from UpdateProposalRequest to prevent over-posting, log swallowed exceptions in ProposalService. Infrastructure: enforce SSL on all S3 buckets, encrypt SQS queues, enable optional MFA on Cognito, add API Gateway access logging. Lambdas: fix _retry_request undefined variable across all 4 Lambdas, re-raise exceptions in pdf-extract/pdf-generate instead of swallowing, add idempotency guard to suggestions Lambda. Web: add ErrorBoundary, add auth loading state to ProtectedRoute, add mutation error toasts in AdminWorkspace, fix dead Cognito link. Mobile: add mutex to offline queue processing, distinguish permanent vs retryable failures, register all screens for both roles, log sync errors. Swagger/OpenAPI: add Swashbuckle with JWT bearer security definition, add ProducesResponseType attributes to key endpoints. Includes AUDIT-REPORT.md with complete findings and CLAUDE.md project instructions. 2026-05-27 15:33:27 -04:00			`- infra/: CDK TypeScript (foundation-stack, compute-stack, frontend-stack)`
			`- shared/: Shared TypeScript API contracts`
			`- scripts/: Local dev helpers`

			`## Auth Model`

			`External: Cognito JWT via API Gateway (web + mobile client IDs, groups: dispatchers/admins/sysadmins)`
docs: update CLAUDE.md audit status for Phase 5 2026-05-27 17:56:43 -04:00			`Internal: Lambdas → .NET Function URL with Secrets Manager API key via custom middleware`
audit: fix all Critical and High security/reliability issues across monorepo 6-domain audit (API, web, mobile, lambdas, infra, QA) with fixes: API security: scope internal API key middleware to allowed paths only, return 401 on invalid key instead of falling through, remove unvalidated JWT code path, sanitize error messages, add UpdateProposal validator, remove status field from UpdateProposalRequest to prevent over-posting, log swallowed exceptions in ProposalService. Infrastructure: enforce SSL on all S3 buckets, encrypt SQS queues, enable optional MFA on Cognito, add API Gateway access logging. Lambdas: fix _retry_request undefined variable across all 4 Lambdas, re-raise exceptions in pdf-extract/pdf-generate instead of swallowing, add idempotency guard to suggestions Lambda. Web: add ErrorBoundary, add auth loading state to ProtectedRoute, add mutation error toasts in AdminWorkspace, fix dead Cognito link. Mobile: add mutex to offline queue processing, distinguish permanent vs retryable failures, register all screens for both roles, log sync errors. Swagger/OpenAPI: add Swashbuckle with JWT bearer security definition, add ProducesResponseType attributes to key endpoints. Includes AUDIT-REPORT.md with complete findings and CLAUDE.md project instructions. 2026-05-27 15:33:27 -04:00
docs: SHOC-alignment Phase 1 — ADRs, governance files, doc corrections (#220) - Add ADR 0002 (SHOC merge boundary: separate backend services, shared conventions) and ADR 0003 (adopt SHOC design system + UI/UX layout) - Add CODEOWNERS (internal-dev) and PR template (Summary/Test plan/Jira/ docs-current checklist + contract-table convention) - Fix stale facts in README/CLAUDE.md: MUI v7→v9, RN 0.85→0.86, OpenSearch Serverless/oss-index-creator → Aurora pgvector/ aurora-pgvector-init (ADR 0001), test counts 149→186 (123 xUnit / 26 vitest / 37 pytest), deploy triggers are workflow_dispatch-only, reusable workflow refs float on @main, aws-cdk-lib version claim replaced with Dependabot-maintained note 2026-07-13 17:00:45 -04:00			`## Key Decisions (ADRs in docs/adr/)`

			- ADR 0001: Bedrock KB vector store is Aurora PostgreSQL + pgvector (replaced OpenSearch Serverless; `oss-index-creator` Lambda replaced by `aurora-pgvector-init`)
			`- ADR 0002: SHOC merge boundary — backends stay separate services permanently (PostgreSQL + Cognito here; SQL Server + ASP.NET Identity in SHOC); consolidation converges on conventions/layers/service patterns, never on platform`
			`- ADR 0003: SHOC dev's design system + UI/UX layout is canonical (Montserrat/DM Sans, primary #1c75bc, 244px sidebar, CSS-variable single-token-source consumed by MUI via getCssVar); the old Nunito/#0c4f6f canon and the interim "Sea Haven Ops" Inter/#2563EB theme are superseded`

audit: fix all Critical and High security/reliability issues across monorepo 6-domain audit (API, web, mobile, lambdas, infra, QA) with fixes: API security: scope internal API key middleware to allowed paths only, return 401 on invalid key instead of falling through, remove unvalidated JWT code path, sanitize error messages, add UpdateProposal validator, remove status field from UpdateProposalRequest to prevent over-posting, log swallowed exceptions in ProposalService. Infrastructure: enforce SSL on all S3 buckets, encrypt SQS queues, enable optional MFA on Cognito, add API Gateway access logging. Lambdas: fix _retry_request undefined variable across all 4 Lambdas, re-raise exceptions in pdf-extract/pdf-generate instead of swallowing, add idempotency guard to suggestions Lambda. Web: add ErrorBoundary, add auth loading state to ProtectedRoute, add mutation error toasts in AdminWorkspace, fix dead Cognito link. Mobile: add mutex to offline queue processing, distinguish permanent vs retryable failures, register all screens for both roles, log sync errors. Swagger/OpenAPI: add Swashbuckle with JWT bearer security definition, add ProducesResponseType attributes to key endpoints. Includes AUDIT-REPORT.md with complete findings and CLAUDE.md project instructions. 2026-05-27 15:33:27 -04:00			`## Request Flow`

			`1. Dispatcher submits proposal (web/mobile) → InReview (no Draft stage)`
			`2. Bedrock RAG suggests line items from pricing library`
			`3. Admin reviews in workspace, edits line items, approves`
			`4. PDF generation queued via SQS → Python Lambda → branded PDF → S3`
			`5. State machine: InReview → Approved → Sent → Revised`

			`## Infrastructure`

chore(infra): prep proposal-system for seahaven-prod deployment (#227) * chore(infra): retarget prod to seahaven-prod account + OIDC deploy-role artifacts Retarget the CDK prod env from mgmt (328440206208, now frozen for workloads) to the dedicated seahaven-prod workload account (011934824531). proposal-system is the org's first prod tenant. Hard-block env=staging (still targets frozen mgmt) in resolveConfig until it is retargeted to seahaven-dev (710827005802). Add a WARN-only out-of-pipeline deploy guard in bin/app.ts. Add infra/deploy-role/: OIDC trust policy (sub scoped to Sea-Haven-Industries/proposal-system:ref:refs/heads/main), least-privilege permissions policy (AssumeRole on the verified cdk-hnb659fds bootstrap roles, deterministic site bucket, account-scoped CloudFront invalidation), and an idempotent creation script. Verified against live prod: bootstrap qualifier hnb659fds v32, OIDC provider present. Passed GPT-4.1 cross-review (APPROVE) and workflow red-team (CLEAN). Role NOT yet created — gated on /sh-security-review + the deploy go-ahead. Docs: README + CLAUDE.md reflect the prod account and pipeline-only deploy. * chore(infra): region-bound deploy-role DescribeStacks to us-east-1 (sh-security-review IAM-L2) * feat(infra): Aurora prod backup retention 14d + window; prod-only CDK context Bump Aurora automated-backup (PITR) retention 7->14d and set a preferred backup window for the prod tenant. Dedicated AWS Backup vault + cross-account restore test is a tracked follow-up (no org central-backup design exists yet). Prune the stale mgmt-account AZ context; prod (011934824531) is the only deploy target. 2026-07-15 14:44:35 -04:00			Deploys to the seahaven-prod account (`011934824531`), us-east-1. (mgmt `328440206208` is frozen for workloads; staging is hard-disabled in `infra/lib/config.ts` until retargeted to seahaven-dev `710827005802`.) Aurora PostgreSQL 15 Serverless v2 (RDS Data API + pgvector), S3, SQS+DLQ, Cognito+Google OAuth, Bedrock KB (Aurora pgvector store — ADR 0001), GitHub Actions OIDC, CloudFront+S3 OAC. Prod deploys run via the `deploy.yaml` pipeline (workflow_dispatch) only — no local `cdk deploy` to prod.
audit: fix all Critical and High security/reliability issues across monorepo 6-domain audit (API, web, mobile, lambdas, infra, QA) with fixes: API security: scope internal API key middleware to allowed paths only, return 401 on invalid key instead of falling through, remove unvalidated JWT code path, sanitize error messages, add UpdateProposal validator, remove status field from UpdateProposalRequest to prevent over-posting, log swallowed exceptions in ProposalService. Infrastructure: enforce SSL on all S3 buckets, encrypt SQS queues, enable optional MFA on Cognito, add API Gateway access logging. Lambdas: fix _retry_request undefined variable across all 4 Lambdas, re-raise exceptions in pdf-extract/pdf-generate instead of swallowing, add idempotency guard to suggestions Lambda. Web: add ErrorBoundary, add auth loading state to ProtectedRoute, add mutation error toasts in AdminWorkspace, fix dead Cognito link. Mobile: add mutex to offline queue processing, distinguish permanent vs retryable failures, register all screens for both roles, log sync errors. Swagger/OpenAPI: add Swashbuckle with JWT bearer security definition, add ProducesResponseType attributes to key endpoints. Includes AUDIT-REPORT.md with complete findings and CLAUDE.md project instructions. 2026-05-27 15:33:27 -04:00
docs(claude): strip completed-audit process relics from CLAUDE.md (#261) Remove the Audit Status section, Agent Delegation Rules pipeline, severity levels, critical-findings list, 65% context pause rule, and AUDIT-REPORT.md references now that the 2026-05-27 audit and remediation are complete. Keep the finding-ID convention (API-C1, WEB-H3, etc.) since those IDs are still embedded in code comments and commit history, and leave all arch/ADR/ infra content untouched. 2026-07-28 19:56:16 -04:00			`## Working Rules`
audit: fix all Critical and High security/reliability issues across monorepo 6-domain audit (API, web, mobile, lambdas, infra, QA) with fixes: API security: scope internal API key middleware to allowed paths only, return 401 on invalid key instead of falling through, remove unvalidated JWT code path, sanitize error messages, add UpdateProposal validator, remove status field from UpdateProposalRequest to prevent over-posting, log swallowed exceptions in ProposalService. Infrastructure: enforce SSL on all S3 buckets, encrypt SQS queues, enable optional MFA on Cognito, add API Gateway access logging. Lambdas: fix _retry_request undefined variable across all 4 Lambdas, re-raise exceptions in pdf-extract/pdf-generate instead of swallowing, add idempotency guard to suggestions Lambda. Web: add ErrorBoundary, add auth loading state to ProtectedRoute, add mutation error toasts in AdminWorkspace, fix dead Cognito link. Mobile: add mutex to offline queue processing, distinguish permanent vs retryable failures, register all screens for both roles, log sync errors. Swagger/OpenAPI: add Swashbuckle with JWT bearer security definition, add ProducesResponseType attributes to key endpoints. Includes AUDIT-REPORT.md with complete findings and CLAUDE.md project instructions. 2026-05-27 15:33:27 -04:00
			`- Never commit secrets, credentials, .env files, or local artifacts`
			`- If secrets found in code: document, remove safely, ensure proper config mechanism`
			`- Preserve existing business logic unless broken, insecure, or contradicted`
			`- Run lint/typecheck/build/test after each phase`
docs: update CLAUDE.md audit status for Phase 5 2026-05-27 17:56:43 -04:00
docs(claude): strip completed-audit process relics from CLAUDE.md (#261) Remove the Audit Status section, Agent Delegation Rules pipeline, severity levels, critical-findings list, 65% context pause rule, and AUDIT-REPORT.md references now that the 2026-05-27 audit and remediation are complete. Keep the finding-ID convention (API-C1, WEB-H3, etc.) since those IDs are still embedded in code comments and commit history, and leave all arch/ADR/ infra content untouched. 2026-07-28 19:56:16 -04:00			`## Finding-ID Convention`
docs: update CLAUDE.md audit status for Phase 5 2026-05-27 17:56:43 -04:00
docs(claude): strip completed-audit process relics from CLAUDE.md (#261) Remove the Audit Status section, Agent Delegation Rules pipeline, severity levels, critical-findings list, 65% context pause rule, and AUDIT-REPORT.md references now that the 2026-05-27 audit and remediation are complete. Keep the finding-ID convention (API-C1, WEB-H3, etc.) since those IDs are still embedded in code comments and commit history, and leave all arch/ADR/ infra content untouched. 2026-07-28 19:56:16 -04:00			Code comments and commit messages reference finding IDs from a prior security-audit remediation (e.g. `API-C1`, `WEB-H3`, `LAM-H4`). These IDs are embedded directly in the codebase, so keep the convention documented:
docs: update CLAUDE.md audit status for Phase 5 2026-05-27 17:56:43 -04:00
docs(claude): strip completed-audit process relics from CLAUDE.md (#261) Remove the Audit Status section, Agent Delegation Rules pipeline, severity levels, critical-findings list, 65% context pause rule, and AUDIT-REPORT.md references now that the 2026-05-27 audit and remediation are complete. Keep the finding-ID convention (API-C1, WEB-H3, etc.) since those IDs are still embedded in code comments and commit history, and leave all arch/ADR/ infra content untouched. 2026-07-28 19:56:16 -04:00			`- Reference finding IDs in commit messages and code comments`
			- Format: `// Fix: API-C1 — scope internal key to /internal/ paths`