# ubaidrmn/lambdacrm architecture

> Architecture diagram of the GitHub repository ubaidrmn/lambdacrm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ubaidrmn/lambdacrm
- Repository: https://github.com/ubaidrmn/lambdacrm

## Overview

##### Project type and purpose
- This is a full-stack, serverless CRM application (“LambdaCRM”).
- Frontend: React app built with Vite and TailwindCSS.
- Backend: Single AWS Lambda function (TypeScript) behind API Gateway.
- Database: DynamoDB with a single-table design.
- Auth: AWS Cognito.
- Infrastructure as code: AWS CDK.
- Local development: Docker Compose with LocalStack.

##### File-structure insights
- Top-level directories:
- backend/ – Lambda code (controllers, services, repositories, schemas, types)
- frontend/ – React app (features, shared components, UI primitives, hooks, lib utilities)
- cdk/ – CDK stacks and tests
- docker-compose.local.yml & localstack-deploy.sh – local dev orchestration
- Backend uses an internal router (route.registry.ts) to dispatch API Gateway requests to controllers.
- Clear separation in backend of controllers → services → repositories → database lib.
- Frontend organized by features (auth, contacts, leads, dashboard, settings, static) and shared/UI components.
- CDK sets up Cognito user pool, API Gateway, Lambda, DynamoDB table, and any IAM roles.

##### Key README architecture notes
- API Gateway → Lambda
- Lambda interacts with DynamoDB (single table)
- Cognito for authentication flows
- Frontend deployed (e.g., S3/CloudFront) and calls same API endpoint
- CDK bootstraps all AWS resources
- LocalStack emulates AWS services locally via Docker Compose

##### Main components
a. User / Browser (React UI)
b. CDN / Hosting (S3 + CloudFront)
c. API Gateway
d. Lambda Function (single entrypoint)
– Internal layers: controllers, services, repositories, data access
e. DynamoDB Table (single-table design)
f. Cognito User Pool (Auth)
g. AWS CDK (IaC – not a runtime component, but used to provision resources)
h. LocalStack + Docker Compose (for local dev)

##### Relationships and data flows
- Browser → HTTP(S) → CDN/Hosting → static React bundle
- Browser → REST API calls → API Gateway → Lambda
- Lambda → SDK calls → DynamoDB
- Browser ↔ Cognito (sign-in/up, tokens)
- Lambda uses Cognito JWT for auth/authorization (via auth.ts lib)
- CDK provisions all AWS components
- Local dev environment: Browser / Local Lambda / Local DynamoDB via LocalStack

##### Architectural patterns & principles
- Serverless microservice (single Lambda) with internal routing
- Single-table design in DynamoDB for all entities (users, leads, projects)
- Layered backend: controllers → services → repositories → database abstraction
- Feature-driven frontend (domain boundaries)
- Infrastructure as code for repeatability & version control

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User and Frontend
    Browser(("User Browser")):::client
    CDN["CDN Hosting (S3/CloudFront)"]:::compute
    Frontend["React App"]:::frontend

    %% AWS Services
    APIGW{"API Gateway"}:::aws
    Cognito(("Cognito User Pool")):::aws
    DynamoDB["DynamoDB Table\n(Single-table design)"]:::database

    %% Lambda and Backend Layers
    subgraph "Lambda Function\n(backend/src/index.ts)" 
        direction TB
        Lambda["AWS Lambda"]:::compute
        subgraph "Backend Layers"
            direction TB
            RouteRegistry["Route Registry"]:::backend
            Controllers["Controllers"]:::backend
            Services["Services"]:::backend
            Repositories["Repositories"]:::backend
            DatabaseLib["Database Lib"]:::backend
            AuthLib["Auth Utils"]:::backend
            Schemas["Schemas"]:::backend
            Types["Shared Types"]:::backend
        end
    end

    %% Infrastructure and Local Dev
    CDK(("AWS CDK (IaC)")):::infra
    subgraph "Local Development\n(LocalStack + Docker Compose)"
        direction TB
        LocalAPIGW["Local API Gateway"]:::aws
        LocalLambda["Local Lambda"]:::compute
        LocalDB["Local DynamoDB"]:::database
    end

    %% Relationships
    Browser -->|HTTP GET| CDN
    CDN -->|Serves React bundle| Browser
    Browser -->|REST API calls| APIGW
    Browser -->|Auth UI| Cognito
    APIGW -->|Invokes| Lambda
    Lambda -->|query/write| DynamoDB
    Lambda -->|validate JWT| Cognito

    %% Local flows
    Browser -->|HTTP| LocalAPIGW
    LocalAPIGW -->|invoke| LocalLambda
    LocalLambda -->|query/write| LocalDB

    %% CDK provisioning
    CDK --> CDN
    CDK --> APIGW
    CDK --> Lambda
    CDK --> DynamoDB
    CDK --> Cognito

    %% Click Events - Frontend
    click Frontend "https://github.com/ubaidrmn/lambdacrm/tree/main/frontend/src"
    click CDN "https://github.com/ubaidrmn/lambdacrm/blob/main/frontend/src/main.tsx"
    click Frontend "https://github.com/ubaidrmn/lambdacrm/blob/main/frontend/src/App.tsx"
    click Frontend "https://github.com/ubaidrmn/lambdacrm/tree/main/frontend/src/features"
    click Frontend "https://github.com/ubaidrmn/lambdacrm/tree/main/frontend/src/components/shared"
    click Frontend "https://github.com/ubaidrmn/lambdacrm/tree/main/frontend/src/components/ui"

    %% Click Events - Backend
    click Lambda "https://github.com/ubaidrmn/lambdacrm/blob/main/backend/src/index.ts"
    click DatabaseLib "https://github.com/ubaidrmn/lambdacrm/blob/main/backend/src/lib/database.ts"
    click RouteRegistry "https://github.com/ubaidrmn/lambdacrm/blob/main/backend/src/lib/route.registry.ts"
    click Controllers "https://github.com/ubaidrmn/lambdacrm/blob/main/backend/src/controllers/lead.controller.ts"
    click Controllers "https://github.com/ubaidrmn/lambdacrm/blob/main/backend/src/controllers/user.controller.ts"
    click Services "https://github.com/ubaidrmn/lambdacrm/blob/main/backend/src/services/lead.service.ts"
    click Services "https://github.com/ubaidrmn/lambdacrm/blob/main/backend/src/services/user.service.ts"
    click Repositories "https://github.com/ubaidrmn/lambdacrm/blob/main/backend/src/repositories/lead.repository.ts"
    click Repositories "https://github.com/ubaidrmn/lambdacrm/blob/main/backend/src/repositories/user.repository.ts"
    click AuthLib "https://github.com/ubaidrmn/lambdacrm/blob/main/backend/src/lib/auth.ts"
    click Schemas "https://github.com/ubaidrmn/lambdacrm/blob/main/backend/src/schemas/lead.schemas.ts"
    click Types "https://github.com/ubaidrmn/lambdacrm/blob/main/backend/src/types/core.ts"
    click Types "https://github.com/ubaidrmn/lambdacrm/blob/main/backend/src/types/lead.model.ts"
    click Types "https://github.com/ubaidrmn/lambdacrm/blob/main/backend/src/types/project.model.ts"
    click Types "https://github.com/ubaidrmn/lambdacrm/blob/main/backend/src/types/user.model.ts"
    click Lambda "https://github.com/ubaidrmn/lambdacrm/blob/main/backend/src/local-runner.ts"
    click LocalDB "https://github.com/ubaidrmn/lambdacrm/blob/main/dynamo-db-local-init.sh"

    %% Click Events - CDK & Dev
    click CDK "https://github.com/ubaidrmn/lambdacrm/blob/main/cdk/lib/cdk-stack.ts"
    click CDK "https://github.com/ubaidrmn/lambdacrm/blob/main/cdk/bin/cdk.ts"
    click CDK "https://github.com/ubaidrmn/lambdacrm/blob/main/cdk/test/cdk.test.ts"
    click LocalAPIGW "https://github.com/ubaidrmn/lambdacrm/blob/main/docker-compose.local.yml"
    click LocalLambda "https://github.com/ubaidrmn/lambdacrm/blob/main/localstack-deploy.sh"

    %% Styles
    classDef client fill:#dddddd,stroke:#333,stroke-width:1px
    classDef compute fill:#cce5ff,stroke:#004085,stroke-width:1px
    classDef aws fill:#ffe5b4,stroke:#ff8c00,stroke-width:1px
    classDef database fill:#d4edda,stroke:#155724,stroke-width:1px
    classDef frontend fill:#f0f0f0,stroke:#333,stroke-width:1px
    classDef backend fill:#e2e3e5,stroke:#6c757d,stroke-width:1px
    classDef infra fill:#f5e1f7,stroke:#6f42c1,stroke-width:1px
```
