# aka-kv/identity-reconciliation architecture

> Architecture diagram of the GitHub repository aka-kv/identity-reconciliation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aka-kv/identity-reconciliation
- Repository: https://github.com/aka-kv/identity-reconciliation

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client to API Gateway
    Client["Client"]:::external
    Client -->|POST /identify| APIGateway

    %% API Gateway
    APIGateway["API Gateway"]:::apigateway

    %% AWS Lambda Application
    APIGateway -->|Trigger Lambda| LambdaHandler
    subgraph "AWS Lambda (FastAPI App)"
        direction TB
        LambdaHandler["Lambda Handler"]:::compute
        LambdaHandler --> MangumAdapter

        MangumAdapter["Mangum Adapter"]:::compute
        MangumAdapter --> RouteDefinitions

        Config["Config Management"]:::layer
        click Config "https://github.com/aka-kv/identity-reconciliation/blob/master/config.py"

        RouteDefinitions["Route Definitions"]:::layer
        click RouteDefinitions "https://github.com/aka-kv/identity-reconciliation/blob/master/main.py"
        RouteDefinitions --> Schemas

        Schemas["Pydantic Schemas"]:::layer
        click Schemas "https://github.com/aka-kv/identity-reconciliation/blob/master/schemas/identify.py"

        RouteDefinitions --> ServiceLogic

        ServiceLogic["identity_service"]:::layer
        click ServiceLogic "https://github.com/aka-kv/identity-reconciliation/blob/master/services/identity_service.py"
        ServiceLogic --> DBSessionFactory

        DBSessionFactory["SQLAlchemy Session Factory"]:::layer
        click DBSessionFactory "https://github.com/aka-kv/identity-reconciliation/blob/master/database.py"
    end

    %% Database Proxy and RDS
    DBSessionFactory --> RDSProxy
    RDSProxy["RDS Proxy"]:::db
    RDSProxy -->|Queries| Postgres
    Postgres["PostgreSQL RDS"]:::db

    Postgres -->|Results| DBSessionFactory

    %% Artifacts
    subgraph "Artifacts"
        direction TB
        Requirements["requirements.txt"]:::artifact
        click Requirements "https://github.com/aka-kv/identity-reconciliation/blob/master/requirements.txt"
        TestPayload["lambda_test.json"]:::artifact
        click TestPayload "https://github.com/aka-kv/identity-reconciliation/blob/master/lambda_test.json"
    end

    %% Styles
    classDef external fill:#bdc3c7,color:#2c3e50,stroke:#7f8c8d;
    classDef apigateway fill:#27ae60,color:#ecf0f1,stroke:#1e8449;
    classDef compute fill:#2980b9,color:#ecf0f1,stroke:#1c5980;
    classDef db fill:#d35400,color:#ecf0f1,stroke:#a84300;
    classDef layer fill:#ecf0f1,color:#2c3e50,stroke:#95a5a6;
    classDef artifact fill:#f1c40f,color:#2c3e50,stroke:#b7950b;
```
