# masanthimanshu/pookie-lambda architecture

> Architecture diagram of the GitHub repository masanthimanshu/pookie-lambda, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/masanthimanshu/pookie-lambda
- Repository: https://github.com/masanthimanshu/pookie-lambda

## Overview

##### What this project is (type + purpose)
From the file tree, this is an **AWS Serverless (Node.js) project** packaged/deployed via **Serverless Framework** (`serverless.yaml`). It implements an **API-oriented Lambda service** with a clear **CQRS-ish split** between:
- **Read path**: `src/read/*`
- **Write path**: `src/write/*`

It also provisions/depends on a **DynamoDB table** (likely) via infrastructure templates in `aws/` (`aws/database.yaml`). The minimal README title (“Add Pookie Data Lambda Function”) suggests the Lambda’s purpose is to add/manage some “Pookie” data, but the architecture is the key: *Lambda + DynamoDB + HTTP entrypoints + validation/schema*.

##### Top-level
- `serverless.yaml`: **primary service definition** (functions, events like HTTP/API Gateway routes, IAM permissions, env vars).
- `aws/database.yaml`: **CloudFormation/SAM-like infra** for DynamoDB (table, indexes, streams, etc.).
- `.github/workflows/*`:
- `lambda-deploy.yaml`: CI/CD pipeline for deploying the Lambda (likely `serverless deploy`).
- `check-issues.yaml`: repo hygiene automation (not runtime, but include in “delivery” view if desired).

##### Runtime code
- `src/read/handler.js`, `src/write/handler.js`: **Lambda entrypoints** (each is a function handler).
- `src/read/routes.js`, `src/write/routes.js`: route definitions (suggests an internal router / mini web framework usage).
- `src/write/controller.js`: write orchestration/business logic.
- `core/create_app.js`: likely builds an app/router abstraction (Express-like) for Lambda handlers.
- `core/dynamo_client.js`: DynamoDB client wrapper (AWS SDK v2/v3).
- `core/runtime_logs.js`: logging utility (structured logs, correlation ids, etc.).
- `data/schema.js`, `data/validator.js`: domain schema + validation logic (input validation for writes, maybe output shaping).

**Lambda Handler → App/Router → Route Handler/Controller → Validation/Schema → DynamoDB client → DynamoDB**

##### Runtime/Request Flow (Container-level)
Main components to include:
##### Client (caller)
2. **API Gateway (or Lambda Function URL)** — *you confirm by reading `serverless.yaml` “events: http/httpApi”*
##### Lambda Functions
- `ReadFunction` (from `src/read/handler.js`)
- `WriteFunction` (from `src/write/handler.js`)
##### DynamoDB Table
- provisioned via `aws/database.yaml`
##### (Optional but recommended) CloudWatch Logs
- because `core/runtime_logs.js` indicates explicit runtime logging

##### Code/Module Architecture (Component-level inside Lambda)
- `handler.js` (entry)
- `create_app.js` (app bootstrap)
- `routes.js` (route mapping)
- `controller.js` (write side)
- `validator.js` + `schema.js` (data validation)
- `dynamo_client.js` (DB adapter)
- DynamoDB (external dependency)

This is where you “separate into as many components as possible” for clarity and correctness.

##### Important architectural patterns/design principles to highlight
- **CQRS-like separation**: distinct read/write functions and modules (`src/read` vs `src/write`)
- **Layering**:
- Entry/transport: handlers
- Routing: routes + create_app
- Business logic: controllers (write)
- Domain integrity: schema + validator
- Persistence adapter: dynamo_client
- **Infrastructure as Code**: `serverless.yaml` and `aws/database.yaml`
- **CI/CD**: GitHub Actions deploy workflow

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Diagram 1: Runtime / Container View
  %% =========================
  subgraph "Runtime / Container View (AWS)"
    direction TB

    Client["Client"]:::external

    APIGW["API Gateway (HTTP API / REST API)"]:::aws

    subgraph "Serverless Service (deployed on AWS)"
      direction TB
      ReadLambda(["Lambda: Read"]):::lambda
      WriteLambda(["Lambda: Write"]):::lambda
    end

    DynamoDB[("DynamoDB Table")]:::db
    CW["CloudWatch Logs"]:::aws

    Client -->|"HTTPS_request"| APIGW
    APIGW -->|"Invoke_(GET/...)"| ReadLambda
    APIGW -->|"Invoke_(POST/PUT/...)"| WriteLambda

    ReadLambda -->|"Get/Query/Scan"| DynamoDB
    WriteLambda -->|"Put/Update"| DynamoDB

    ReadLambda -->|"Structured_logs"| CW
    WriteLambda -->|"Structured_logs"| CW
  end

  %% =========================
  %% Diagram 2: Component / Code Architecture View
  %% =========================
  subgraph "Component View (inside Lambdas)"
    direction TB

    subgraph "Shared Core (used by Read + Write)"
      direction TB
      CreateApp["core/create_app.js\nApp/Router Bootstrap"]:::core
      DynamoClient["core/dynamo_client.js\nDynamoDB Client Wrapper"]:::core
      RuntimeLogs["core/runtime_logs.js\nRuntime Logging Utility"]:::core
    end

    subgraph "Read Path (CQRS Read)"
      direction TB
      RH["src/read/handler.js\nRead Handler"]:::code
      RR["src/read/routes.js\nRead Routes"]:::code
      RH -->|"build_app"| CreateApp
      CreateApp -->|"mount_routes"| RR
      RR -->|"read_ops"| DynamoClient
      RH -->|"use_logger"| RuntimeLogs
      RR -->|"log_events"| RuntimeLogs
    end

    subgraph "Write Path (CQRS Write)"
      direction TB
      WH["src/write/handler.js\nWrite Handler"]:::code
      WR["src/write/routes.js\nWrite Routes"]:::code
      WC["src/write/controller.js\nWrite Controller"]:::code

      Validator["data/validator.js\nInput Validation"]:::data
      Schema["data/schema.js\nDomain Schema"]:::data

      WH -->|"build_app"| CreateApp
      CreateApp -->|"mount_routes"| WR
      WR -->|"delegate"| WC

      WC -->|"validate_input"| Validator
      Validator -->|"uses"| Schema

      WC -->|"write_ops"| DynamoClient

      WH -->|"use_logger"| RuntimeLogs
      WR -->|"log_events"| RuntimeLogs
      WC -->|"log_events"| RuntimeLogs
    end

    DynamoClient -->|"AWS_SDK_calls"| DynamoDB
  end

  %% =========================
  %% Diagram 3: Delivery / IaC / CI-CD View
  %% =========================
  subgraph "Delivery / IaC"
    direction TB

    Dev["Developer"]:::external
    GH["GitHub Actions"]:::cicd
    DeployWF["Workflow: lambda-deploy.yaml"]:::cicd
    CheckIssuesWF["Workflow: check-issues.yaml"]:::cicd

    SLSSvc["Serverless Framework Service Definition"]:::iac
    DBInfra["DynamoDB Infrastructure Template"]:::iac

    AWSCloud["AWS Account / CloudFormation"]:::aws

    Dev -->|"git_push"| GH
    GH -->|"runs"| DeployWF
    GH -->|"runs"| CheckIssuesWF

    DeployWF -->|"serverless_deploy"| SLSSvc
    SLSSvc -->|"provision/update"| AWSCloud
    DBInfra -->|"provision/update"| AWSCloud

    AWSCloud -->|"creates"| APIGW
    AWSCloud -->|"creates"| ReadLambda
    AWSCloud -->|"creates"| WriteLambda
    AWSCloud -->|"creates"| DynamoDB
  end

  %% =========================
  %% Click Events (from component_mapping)
  %% =========================
  click SLSSvc "https://github.com/masanthimanshu/pookie-lambda/blob/main/serverless.yaml"
  click DBInfra "https://github.com/masanthimanshu/pookie-lambda/blob/main/aws/database.yaml"
  click DeployWF "https://github.com/masanthimanshu/pookie-lambda/blob/main/.github/workflows/lambda-deploy.yaml"
  click CheckIssuesWF "https://github.com/masanthimanshu/pookie-lambda/blob/main/.github/workflows/check-issues.yaml"

  click RH "https://github.com/masanthimanshu/pookie-lambda/blob/main/src/read/handler.js"
  click RR "https://github.com/masanthimanshu/pookie-lambda/blob/main/src/read/routes.js"
  click WH "https://github.com/masanthimanshu/pookie-lambda/blob/main/src/write/handler.js"
  click WR "https://github.com/masanthimanshu/pookie-lambda/blob/main/src/write/routes.js"
  click WC "https://github.com/masanthimanshu/pookie-lambda/blob/main/src/write/controller.js"

  click CreateApp "https://github.com/masanthimanshu/pookie-lambda/blob/main/core/create_app.js"
  click DynamoClient "https://github.com/masanthimanshu/pookie-lambda/blob/main/core/dynamo_client.js"
  click RuntimeLogs "https://github.com/masanthimanshu/pookie-lambda/blob/main/core/runtime_logs.js"

  click Schema "https://github.com/masanthimanshu/pookie-lambda/blob/main/data/schema.js"
  click Validator "https://github.com/masanthimanshu/pookie-lambda/blob/main/data/validator.js"

  %% =========================
  %% Styles
  %% =========================
  classDef external fill:#ffffff,stroke:#6b7280,stroke-width:1.5,color:#111827
  classDef aws fill:#eef2ff,stroke:#4338ca,stroke-width:1.5,color:#111827
  classDef lambda fill:#ede9fe,stroke:#6d28d9,stroke-width:2,color:#111827
  classDef db fill:#ecfeff,stroke:#0e7490,stroke-width:2,color:#111827
  classDef code fill:#f0fdf4,stroke:#166534,stroke-width:1.5,color:#052e16
  classDef core fill:#fff7ed,stroke:#9a3412,stroke-width:1.5,color:#7c2d12
  classDef data fill:#fdf2f8,stroke:#9d174d,stroke-width:1.5,color:#831843
  classDef cicd fill:#f8fafc,stroke:#0f172a,stroke-width:1.5,color:#0f172a
  classDef iac fill:#fefce8,stroke:#a16207,stroke-width:1.5,color:#713f12
```
