adam/proposal-system
1
0
Fork 0
mirror of https://github.com/Sea-Haven-Industries/proposal-system.git synced 2026-09-30 04:13:13 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
proposal-system/CLAUDE.md
Adam Moussa a4b09eb0ad
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

4.4 KiB
Raw Blame History

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)