mirror of
https://github.com/Sea-Haven-Industries/proposal-system.git
synced 2026-10-01 04:43:13 +00:00
a4b09eb0ad
- 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
83 lines
No EOL
4.4 KiB
Markdown
83 lines
No EOL
4.4 KiB
Markdown
# 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
|
|
|
|
AWS us-east-1, 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
|
|
|
|
## Agent Delegation Rules
|
|
|
|
### For audit and hardening work, use the Explore-Plan-Execute pipeline:
|
|
|
|
1. Spawn specialist subagents for parallel investigation (api-security, web-audit, mobile-audit, lambda-pipeline, infra-cicd, qa-testing)
|
|
2. Consolidate findings into AUDIT-REPORT.md before implementing
|
|
3. Prioritize: Critical > High > Medium > Low
|
|
4. Implement fixes in logical phases, commit after each phase
|
|
5. Use separate git worktrees/branches for parallel implementation where safe
|
|
|
|
### 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
|
|
- If context reaches 65%, pause, commit, update AUDIT-REPORT.md with HANDOFF ADDENDUM
|
|
|
|
### Severity Levels
|
|
|
|
- **Critical**: security/data exposure/auth bypass/data corruption
|
|
- **High**: broken core workflow, deployment blocker, missing authz, invalid infra
|
|
- **Medium**: reliability, validation, logging, test gaps
|
|
- **Low**: cleanup, DX, docs, polish
|
|
|
|
## Audit Status
|
|
|
|
AUDIT-REPORT.md completed 2026-05-27. 5 Critical, 36 High, 75+ Medium, 60+ Low findings. Phase 1-5 complete: all Critical/High fixed, 17 Medium fixed, CI runs 186 tests (123 xUnit, 26 vitest, 37 pytest).
|
|
|
|
### Critical Findings (fix first)
|
|
|
|
- **API-C1**: InternalApiKeyMiddleware applies globally, bypasses JWT on any route
|
|
- **API-C2**: JWT signature validation skipped when Authority is empty
|
|
- **WEB-C1**: JWT stored in localStorage (XSS token theft)
|
|
- **LAM-C1 / INF-H1**: Function URL authType NONE, publicly accessible
|
|
- **QA-C1**: Zero test coverage, no test projects, CI runs no tests
|
|
|
|
### Remediation Conventions
|
|
|
|
- Reference finding IDs (API-C1, WEB-H3, LAM-H4, etc.) in commit messages and code comments
|
|
- Format: `// Fix: API-C1 — scope internal key to /internal/ paths`
|
|
- Update AUDIT-REPORT.md after each phase: mark fixed findings, note deferred items
|
|
- Parallel-safe worktree splits: api/ changes, web/ changes, and infra/ changes don't conflict
|
|
- Verify after each phase: `dotnet build` (api), `npx tsc --noEmit` (web), `npx cdk synth` (infra) |