Testco Claims Management System

Displaimer: this document was partially written by AI.

An AWS based, full-stack claims management platform built for e-commerce merchants and their customers. The system provides a secure, scalable solution for handling various claims, returns, and customer disputes.

System Architecture

Testco follows a serverless architecture deployed on AWS, designed for high availability, security, and cost-effectiveness. The system consists of a React SPA frontend, FastAPI Lambda backend, Aurora DSQL database, and AWS Cognito for authentication.

Core Design Principles

1. Security First

• JWT Authentication - All merchant operations require valid tokens
• Multi-tenant Architecture - Foundation for future data isolation between merchants
• Public/Private API Separation - Customers (claimants) access limited, public endpoints only
• AWS Cognito Integration - Secure user management implementation
• No Sensitive Data Exposure - Customer data protected from unauthorized access

2. Serverless & Cost-Optimized

• Lambda Functions - Pay-per-request backend with automatic scaling
• Aurora DSQL - Serverless PostgreSQL with per-query pricing
• Static Frontend - Deployed to CloudFront CDN for caching and low latency
• Infrastructure as Code - AWS CDK for reproducible deployments

3. Developer Experience

• Type Safety - End-to-end TypeScript with auto-generated API types
• Modern Tooling - UV (Python), Vite (Frontend), Biome (Linting)
• Comprehensive Testing - Unit, integration, and e2e test suites
• Database Migrations - Version-controlled schema changes via Alembic

4. User-Centric Workflow

The system implements a dual-interface pattern:

• Merchants - Full dashboard with authentication for claim management
• Customers - Simple, public forms for claim submission (no login required)

Project Structure

testco/
├── frontend/          # React SPA with TypeScript
├── backend/           # FastAPI Lambda function  
├── infra/             # AWS CDK infrastructure
└── scripts/           # Utility scripts and tools

Component Overview

Frontend (/frontend/)

Technology: React 19 + TypeScript + TailwindCSS
Key Features:

• Merchant dashboard with authentication via AWS Amplify
• Customer-facing public claim forms
• Type-safe API client auto-generated from OpenAPI schema
• Modern UI components with Radix UI primitives

Backend (/backend/)

Technology: FastAPI + SQLModel + AWS Lambda
Key Features:

• Dual API design (protected merchant endpoints + public customer endpoints)
• JWT authentication with AWS API Gateway integration
• Database ORM with automatic migrations
• Comprehensive test coverage

For detailed backend documentation, see backend/README.md

Infrastructure (/infra/)

Technology: AWS CDK (TypeScript)
Resources:

• Lambda function with container deployment
• Aurora DSQL serverless database
• CloudFront distribution for frontend
• Cognito User Pool for authentication
• API Gateway with JWT authorizer

Scripts (/scripts/)

Utility Tools:

• User management scripts for Cognito
• Database seeding and testing utilities

Key Workflows

1. Claim Creation & Submission

1. Merchant creates claim via authenticated dashboard
2. Customer receives claim link and submits details (no login)
3. Merchant reviews submission and makes approval decision
4. System tracks full audit trail with timestamps

2. Authentication Flow

• Merchants - AWS Cognito authentication with multi-tenant support
• Customers - No authentication required for claim submission
• API Security - JWT tokens validated at AWS API Gateway level

3. Data Isolation

• Tenant ID embedded in JWT claims for merchant operations (will be later combined for separate App Clients)
• Public endpoints provide limited data access for customers
• Database will use scheme per tenant later

Development

Each component has its own development environment and toolchain:

• Frontend: npm run dev (Vite dev server with HMR)
• Backend: uv run commands for testing and local development
• Infrastructure: cdk deploy for AWS resource management
• Testing: Component-specific test suites with CI/CD integration

Technology Choices

Why FastAPI + Lambda?

• Performance - Populat modern Python framework with automatic OpenAPI generation
• Cost - Pay-per-request pricing ideal for variable workloads
• Scalability - Automatic scaling to zero when idle
• Type Safety - Pydantic models provide runtime validation

Why Aurora DSQL?

• Serverless - No server management, scales to zero
• Cost-Effective - Pay only for queries executed
• PostgreSQL Compatible - Not 100% but enought for production use
• Multi-Region - Built-in high availability