How aka-kv/identity-reconciliation works
Project type and purpose
• This is a serverless backend application (“Identity Reconciliation System”) built with FastAPI, deployed on AWS Lambda. Its sole responsibility is to accept identity‐linking requests (email/phone) via an HTTP API, execute reconciliation logic, and persist results in PostgreSQL.
File structure
• Top level:
• lambda_handler.py – AWS Lambda entrypoint (invokes FastAPI via Mangum)
• main.py – FastAPI application setup (routes, middleware, etc.)
• config.py – environment/config management
• database.py – SQLAlchemy engine/session factory using DATABASE_URL
• models/ – SQLAlchemy ORM models (Contact, Base)
• schemas/ – Pydantic request/response schemas (IdentifyPayload)
• services/ – business logic (identity_service.py)
• requirements.txt – Python dependencies (FastAPI, SQLAlchemy, Mangum, psycopg2, etc.)
• lambda_test.json – sample event payload
README for additional insights
• AWS architecture: API Gateway → Lambda → RDS Proxy → PostgreSQL RDS
• Business logic: “Identity Linking” based on email/phone, primary/secondary hierarchy
• Deployment: AWS Lambda behind API Gateway, RDS Proxy sits between Lambda and RDS for pooling
Main components
a. API Gateway (public HTTP endpoint)
b. AWS Lambda (FastAPI app)
– main.py registers POST /identify → calls service → returns schema
– lambda_handler.py wraps FastAPI via Mangum
c. RDS Proxy (connection pooling)
d. PostgreSQL RDS (persistent contact storage)
e. Internal application layers:
1. Controller layer (FastAPI route + Pydantic schemas)
2. Service layer (identity reconciliation logic)
3. Data layer (SQLAlchemy models + database session)
Relationships & data flows
1. Client → HTTP POST → API Gateway
2. API Gateway → triggers Lambda (Mangum adapter → FastAPI)
3. FastAPI route → payload validated by Pydantic schema → call identity_service
4. identity_service → uses SQLAlchemy session (from database.py) → issues queries via RDS Proxy
5. RDS Proxy → multiplexes connections → PostgreSQL RDS → returns query result
6. Service assembles Contact model, commits or merges, returns domain object
7. FastAPI returns Pydantic schema response → Lambda → API Gateway → Client
Architectural patterns & design principles
• Layered architecture: presentation (FastAPI), business (services), persistence (SQLAlchemy)
• Serverless microservice: stateless compute (Lambda) behind API Gateway
• Database connection pooling via RDS Proxy for high concurrency
• Pydantic for input validation, SQLAlchemy for ORM
Detail is crucial
• Don’t just show “Backend → Database.” Show: HTTP API Gateway → Lambda (Mangum → FastAPI route → service → database session) → RDS Proxy → PostgreSQL RDS
• Error/edge flows if necessary: e.g., validation errors, DB constraint failures