proposal-system/README.md

Proposal System

Internal proposal management platform for Sea Haven Industries. Dispatchers submit proposal requests, AI generates draft line items from historical data via Bedrock RAG, admins review and approve in a pricing workspace, and the system produces branded PDFs for delivery.

Architecture Overview

Monorepo with five primary services:

• .NET 8 API -- Clean Architecture REST API hosted on Lambda behind API Gateway (JWT-authorized) with Function URL (AWS_IAM) for internal access
• React 19 Web -- MUI v7 admin/dispatcher workspace served via CloudFront + S3
• React Native Mobile -- iOS-first field app for dispatchers (offline-capable)
• Python Lambdas -- PDF extraction, PDF generation, library ingestion, AI suggestions, AOSS index provisioning
• CDK Infrastructure -- Three TypeScript stacks managing all AWS resources

Repository Structure

proposal-system/
├── api/            .NET 8 Web API (Lambda-hosted, EF Core + PostgreSQL)
├── web/            React 19 + MUI v7 + Vite frontend
├── mobile/         React Native 0.85 iOS app
├── lambdas/        Python 3.12 processing functions (arm64)
├── infra/          CDK TypeScript (3 stacks)
├── shared/         TypeScript API contracts (shared between web + mobile)
├── scripts/        Post-deploy and utility scripts
├── .github/        CI/CD workflows
└── docker-compose.yml

Tech Stack

Component	Technologies
API	.NET 8, ASP.NET Core, EF Core + Npgsql, FluentValidation, Cognito JWT, Amazon.Lambda.AspNetCoreServer
Web	React 19, TypeScript, MUI v7, Vite, Redux Toolkit, TanStack Query, axios
Mobile	React Native CLI 0.85, React 19, React Native Paper, React Navigation, react-native-app-auth (PKCE), amazon-cognito-identity-js (SRP), Keychain, offline draft queue
Lambdas	Python 3.12, arm64, pdfplumber, reportlab, httpx, boto3
Infrastructure	CDK TypeScript (aws-cdk-lib 2.253.1)
AI/RAG	Bedrock Knowledge Base (Titan Embeddings v2), OpenSearch Serverless (VPC-only), Claude Sonnet via Bedrock cross-region inference
Auth	Cognito User Pool + Google OAuth IdP (groups: dispatchers, admins, sysadmins)

AWS Resources

All resources are in us-east-1 (account 328440206208).

CDK Stack	Key Resources
proposal-system-foundation	RDS PostgreSQL 15 (t4g.small), S3 buckets, SQS queue + DLQ, Cognito user pool, Secrets Manager
proposal-system-compute	API Gateway HTTP API (JWT authorizer + access logging), .NET 8 API Lambda + Function URL (AWS_IAM), Python Lambdas (pdf-extract, pdf-generate, library-ingest, suggestions, oss-index-creator), OpenSearch Serverless collection (VPC endpoint), Bedrock KB
proposal-system-frontend	CloudFront distribution (S3 OAC)

Resource Type	Names
S3 Buckets	proposal-system-uploads, proposal-system-generated, proposal-system-library, seahaven-ios-certificates
SQS	proposal-system-jobs (720s visibility, SQS-managed encryption, reportBatchItemFailures) + proposal-system-jobs-dlq (SQS-managed encryption, message body filtering by jobType)
Secrets	proposal-system/db-credentials, proposal-system/internal-api-key

Local Development

Prerequisites

• .NET 8 SDK
• Node.js 24+
• Python 3.12
• PostgreSQL 16 (via docker-compose or native)

Database

docker compose up -d    # starts PostgreSQL on port 5432
# database: proposalsystem, password: localdev

API

cd api
dotnet restore
dotnet run --project src/ProposalSystem.Api
# runs on http://localhost:5000

In development mode (DevMode=true in appsettings.Development.json):

• JWT auth uses a local symmetric HMAC key (no Cognito required)
• S3 service returns fake presigned URLs
• SQS publisher logs messages without sending

Web Frontend

cd web
npm install
npm run dev
# runs on http://localhost:5173, proxies /api to localhost:5000

When VITE_COGNITO_CLIENT_ID is not set, the login screen shows role-selector buttons for local development.

Infrastructure

cd infra
npm install
npx cdk synth

CI/CD

CI (on pull request to main)

Seven parallel jobs calling org reusable workflows:

Job	Workflow	What it checks
.NET Build & Test	ci-dotnet.yaml	Restore, build, test the API solution (104 xUnit tests)
Web Frontend Check	ci-typescript-cdk.yaml	TypeScript typecheck for web
Web Tests	ci-typescript-cdk.yaml	vitest suite (26 tests — auth, interceptors, components)
Mobile Typecheck	ci-typescript-cdk.yaml	TypeScript typecheck for mobile
Python Lint	ci-python-sam.yaml	ruff check + format on lambdas/
Python Tests	ci-python-sam.yaml	pytest suite (19 tests — pdf-generate, suggestions handlers)
CDK Synth	ci-typescript-cdk.yaml	Synthesize CDK stacks (includes .NET publish)

Deploy (on push to main)

Calls cd-cdk.yaml reusable workflow:

1. Publishes .NET 8 API and Python Lambdas
2. Runs cdk deploy --all
3. Executes scripts/post-deploy.sh (builds web, syncs to S3, invalidates CloudFront)

Deploy uses OIDC role githubdeploy-proposal-system. Concurrency group prevents parallel deploys.

Mobile Deploy

Workflow: deploy-mobile.yaml -- builds and uploads to TestFlight via cd-mobile-ios.yaml reusable workflow on macos-26.

Triggers:

• Automatic: push to main with changes in mobile/**
• Manual: workflow_dispatch for on-demand builds

Mobile iOS

The iOS app uses Fastlane with match for code signing. Certificates and profiles are stored in the seahaven-ios-certificates S3 bucket (versioning enabled, public access blocked).

Build and upload to TestFlight is handled by the cd-mobile-ios.yaml reusable workflow. Required secrets:

Secret	Purpose
AWS_DEPLOY_ROLE_ARN	OIDC role for match S3 access
MATCH_PASSWORD	Decryption passphrase for signing assets
ASC_KEY_ID	App Store Connect API key ID
ASC_ISSUER_ID	App Store Connect issuer
ASC_KEY_CONTENT	App Store Connect API key (base64)

Authentication & Authorization

Two-layer auth architecture with defense-in-depth:

Path	Authorizer	Authentication
External clients → API Gateway /{proxy+}	Cognito JWT authorizer (web + mobile client IDs)	.NET JWT middleware (ValidateAudience=true)
/api/health	None (public)	None
/api/auth/callback, /api/auth/dev-login	None (unauthenticated)	None (pre-auth endpoints)
Internal Lambdas → Function URL	AWS_IAM (grantInvokeUrl)	Internal API key (X-Internal-Api-Key header, value from Secrets Manager)

Role-based access: Cognito groups (dispatchers, admins, sysadmins) map to API roles via cognito:groups claim. Dispatchers can only see their own proposals (ownership enforced in service layer). VendorProposals and GeneratedPdfs endpoints restricted to admins/sysadmins.

Internal API key: Python Lambdas call the .NET API via a Lambda Function URL with AWS_IAM auth (bypasses API Gateway JWT check). The InternalApiKeyMiddleware validates the X-Internal-Api-Key header and assigns the admins role to the synthetic identity. Lambdas cache the API key from Secrets Manager with a 5-minute TTL.

Data Flow

1. Dispatcher submits proposal request (web or mobile)
2. API creates proposal record (with advisory-locked number generation), publishes SQS message
3. If vendor PDF attached: pdf-extract Lambda parses and structures data
4. Suggestions Lambda queries Bedrock KB for similar proposals, generates line items via Claude
5. Admin reviews/edits line items in pricing workspace
6. On approval: pdf-generate Lambda creates branded PDF
7. On send: library-ingest Lambda adds approved proposal to KB for future matching

Failed SQS messages are reported via batchItemFailures and retried up to 3 times before moving to the DLQ.

Testing

149 tests across three stacks, all run in CI on every PR:

Suite	Framework	Count	Coverage
.NET API	xUnit	104	State machine transitions, authorization attributes, middleware, validators, ProposalNumberGenerator, LineItemService state guards
Web	vitest	26	ProtectedRoute, RoleGuard, API client interceptor (401 logout, token attachment)
Python Lambdas	pytest	19	pdf-generate and suggestions handler contracts

cd api && dotnet test          # .NET tests
cd web && npm test             # vitest
cd lambdas && python -m pytest # pytest

Security

Hardening applied across all layers (see AUDIT-REPORT.md for full details):

• Auth: Cognito JWT validation with audience check, startup fails if auth not configured, DevMode gated to IsDevelopment()
• API: FluentValidation on all DTOs, generic error responses (no stack traces or config leaks), structured audit logging with before/after diffs
• Function URL: AWS_IAM auth + internal API key (two-layer defense)
• Infrastructure: S3 enforceSSL + BLOCK_ALL, SQS managed encryption, OpenSearch VPC-only, Cognito optional TOTP MFA, API Gateway access logging
• Lambdas: Prompt injection sanitization, PDF size limits, numeric validation on AI suggestions, S3 key sanitization, idempotent SQS processing
• CI/CD: OIDC (no long-lived credentials), SHA-pinned workflow refs, --require-approval broadening on local deploys
• Web: sessionStorage for tokens (not localStorage), error boundaries, role guards on all admin routes, 401 interceptor clears auth state