# Proposal System - Claude Code Project Memory

> For Sea Haven org-wide governance (branching, PR conventions, secrets policy), see [AGENTS.md](./AGENTS.md).

## 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`