# maoragai12/nx-aws-sam architecture

> Architecture diagram of the GitHub repository maoragai12/nx-aws-sam, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/maoragai12/nx-aws-sam
- Repository: https://github.com/maoragai12/nx-aws-sam

## Overview

##### Project type and purpose
- This is an Nx-based TypeScript monorepo starter for serverless microservices on AWS (AWS SAM + Lambda + API Gateway).
- It provides scaffolding (via `tools/generators/service`) to spin up independent “services” (e.g. `user-service`), each with its own SAM template, handlers, business logic, tests, and CI/CD support (GitHub Actions).

##### File structure
- Top-level config: `.eslintrc.yml`, `jest.config.ts`, `nx.json`, `workspace.json` – these govern linting, testing, workspace layout.
- `services/`: each subfolder (`user-service`, etc.) is a discrete SAM stack. Inside each:
- `template.yaml` (SAM template defining Lambda functions & API Gateway events)
- `src/handler/*.ts` (Lambda handlers)
- `src/service`, `src/repository`, `src/provider`, `src/util` (layered code organization)
- `event.json`, `.env.template.json`, tests.
- `tools/generators/service`: an Nx code generator that copies a folder template into `services/<name>-service`.
- `.github/workflows`: CI/CD pipelines for PR checks, dev deploy, prod deploy.

##### Key insights from README
- Monorepo orchestrated by Nx.
- Automated code generators produce microservice scaffolding.
- AWS SAM handles packaging and deployment (via S3 buckets, CloudFormation stacks).
- GitHub Actions runs only on affected services (lint, test, build, deploy).
- Lambdas expose HTTP endpoints via API Gateway; environment variables managed through SAM template referencing Secrets Manager/SSM.

##### Final recommendations
- Service independently but show shared infrastructure (S3 bucket, pipeline).
- Detail the layered code within a service as an inset or zoom-in: handler → service → repository.
- Workflow: developer change → Nx affected commands → build & deploy via SAM → AWS CloudFormation → live API.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Swimlane: Local Development & Monorepo
    subgraph "Local Development & Monorepo"
        direction TB
        Dev["Developer Workstation (VSCode + Nx CLI + Docker)"]:::dev
        GitHub["GitHub Repository"]:::dev
        Dev -->|"push code"| GitHub

        subgraph "Monorepo Configuration"
            direction TB
            NxJson["nx.json"]:::monorepo
            WorkspaceJson["workspace.json"]:::monorepo
            TsconfigBase["tsconfig.base.json"]:::monorepo
        end
        GitHub --> NxJson
        GitHub --> WorkspaceJson
        GitHub --> TsconfigBase

        subgraph "Top-Level Tooling & Config"
            direction TB
            ESLintCfg[".eslintrc.yml"]:::monorepo
            JestConfig["jest.config.ts"]:::monorepo
            JestPreset["jest.preset.js"]:::monorepo
            PackageJson["package.json"]:::monorepo
        end
        GitHub --> ESLintCfg
        GitHub --> JestConfig
        GitHub --> JestPreset
        GitHub --> PackageJson

        subgraph "Code Generators (service schematic)"
            direction TB
            GenIndex["index.ts"]:::monorepo
            GenSchemaJson["schema.json"]:::monorepo
            GenSchemaTs["schema.ts"]:::monorepo
            GenWorkspaceConfig["workspace.config.ts"]:::monorepo
            GenFiles["files/…"]:::monorepo
        end
        GitHub --> GenIndex
        GitHub --> GenSchemaJson
        GitHub --> GenSchemaTs
        GitHub --> GenWorkspaceConfig
        GitHub --> GenFiles
    end

    %% Swimlane: CI/CD
    subgraph "CI/CD (GitHub Actions)"
        direction TB
        PRWorkflow["pr.yaml"]:::ci
        DeployDev["deploy-dev.yaml"]:::ci
        DeployProd["deploy-prod.yaml"]:::ci
        GitHub --> PRWorkflow
        GitHub --> DeployDev
        GitHub --> DeployProd
    end

    PRWorkflow -->|"Nx affected: lint/test/build"| SAMPkg["AWS SAM CLI"]:::awsInfra
    DeployDev --> SAMPkg
    DeployProd --> SAMPkg

    SAMPkg -->|"package & upload"| S3["S3: sam-artifacts-bucket"]:::awsInfra
    S3 --> CloudFormation["CloudFormation Stack"]:::awsInfra

    %% Swimlane: AWS Cloud
    subgraph "AWS Cloud"
        direction TB
        APIGW["API Gateway"]:::awsInfra
        CloudFormation --> APIGW

        subgraph "Microservices"
            direction TB
            subgraph "user-service Stack"
                direction TB
                Template["template.yaml"]:::awsInfra
                EnvTemplate[".env.template.json"]:::awsInfra
                ESLintSvc[".eslintrc.yml"]:::awsInfra
                TSConfigApp["tsconfig.app.json"]:::awsInfra
                TSConfigSpec["tsconfig.spec.json"]:::awsInfra

                Template --> APIGW

                subgraph "Lambda Functions"
                    direction TB
                    AddHandler["add-user-handler.ts"]:::awsInfra
                    GetHandler["get-user-handler.ts"]:::awsInfra
                end
                APIGW --> AddHandler
                APIGW --> GetHandler

                subgraph "Business Logic Layer"
                    direction TB
                    ServiceLayer["service/"]:::data
                end
                AddHandler --> ServiceLayer
                GetHandler --> ServiceLayer

                subgraph "Repository Layer"
                    direction TB
                    RepoLayer["repository/"]:::data
                end
                ServiceLayer --> RepoLayer

                subgraph "Provider Layer"
                    direction TB
                    ProviderLayer["provider/"]:::data
                end
                ServiceLayer --> ProviderLayer

                subgraph "Utility Functions"
                    direction TB
                    UtilLayer["util/"]:::data
                end
                AddHandler --> UtilLayer
                GetHandler --> UtilLayer

                subgraph "Tests & Samples"
                    direction TB
                    AddTest["add-user-handler.test.ts"]:::monorepo
                    GetTest["get-user-handler.test.ts"]:::monorepo
                    EventJson["event.json"]:::monorepo
                    EnvSvcTemplate[".env.template.json"]:::monorepo
                    JestSvcConfig["jest.config.js"]:::monorepo
                end
                AddHandler --> AddTest
                GetHandler --> GetTest
                AddHandler --> EventJson
                GetHandler --> EventJson
            end
        end

        subgraph "Secrets & Config"
            direction TB
            Secrets["Secrets Manager / SSM"]:::data
        end
        AddHandler --> Secrets
        GetHandler --> Secrets

        subgraph "Data Stores"
            direction TB
            DataStore["DynamoDB / Other"]:::data
        end
        RepoLayer --> DataStore
    end

    %% Click Events
    click NxJson "https://github.com/maoragai12/nx-aws-sam/blob/main/nx.json"
    click WorkspaceJson "https://github.com/maoragai12/nx-aws-sam/blob/main/workspace.json"
    click TsconfigBase "https://github.com/maoragai12/nx-aws-sam/blob/main/tsconfig.base.json"
    click ESLintCfg "https://github.com/maoragai12/nx-aws-sam/blob/main/.eslintrc.yml"
    click JestConfig "https://github.com/maoragai12/nx-aws-sam/blob/main/jest.config.ts"
    click JestPreset "https://github.com/maoragai12/nx-aws-sam/blob/main/jest.preset.js"
    click PackageJson "https://github.com/maoragai12/nx-aws-sam/blob/main/package.json"
    click GenIndex "https://github.com/maoragai12/nx-aws-sam/blob/main/tools/generators/service/index.ts"
    click GenSchemaJson "https://github.com/maoragai12/nx-aws-sam/blob/main/tools/generators/service/schema.json"
    click GenSchemaTs "https://github.com/maoragai12/nx-aws-sam/blob/main/tools/generators/service/schema.ts"
    click GenWorkspaceConfig "https://github.com/maoragai12/nx-aws-sam/blob/main/tools/generators/service/workspace.config.ts"
    click GenFiles "https://github.com/maoragai12/nx-aws-sam/tree/main/tools/generators/service/files/"
    click PRWorkflow "https://github.com/maoragai12/nx-aws-sam/blob/main/.github/workflows/pr.yaml"
    click DeployDev "https://github.com/maoragai12/nx-aws-sam/blob/main/.github/workflows/deploy-dev.yaml"
    click DeployProd "https://github.com/maoragai12/nx-aws-sam/blob/main/.github/workflows/deploy-prod.yaml"
    click Template "https://github.com/maoragai12/nx-aws-sam/blob/main/services/user-service/template.yaml"
    click EnvTemplate "https://github.com/maoragai12/nx-aws-sam/blob/main/services/user-service/.env.template.json"
    click ESLintSvc "https://github.com/maoragai12/nx-aws-sam/blob/main/services/user-service/.eslintrc.yml"
    click TSConfigApp "https://github.com/maoragai12/nx-aws-sam/blob/main/services/user-service/tsconfig.app.json"
    click TSConfigSpec "https://github.com/maoragai12/nx-aws-sam/blob/main/services/user-service/tsconfig.spec.json"
    click AddHandler "https://github.com/maoragai12/nx-aws-sam/blob/main/services/user-service/src/handler/add-user-handler.ts"
    click GetHandler "https://github.com/maoragai12/nx-aws-sam/blob/main/services/user-service/src/handler/get-user-handler.ts"
    click ServiceLayer "https://github.com/maoragai12/nx-aws-sam/tree/main/services/user-service/src/service/"
    click RepoLayer "https://github.com/maoragai12/nx-aws-sam/tree/main/services/user-service/src/repository/"
    click ProviderLayer "https://github.com/maoragai12/nx-aws-sam/tree/main/services/user-service/src/provider/"
    click UtilLayer "https://github.com/maoragai12/nx-aws-sam/tree/main/services/user-service/src/util/"
    click AddTest "https://github.com/maoragai12/nx-aws-sam/blob/main/services/user-service/tests/handler/add-user-handler.test.ts"
    click GetTest "https://github.com/maoragai12/nx-aws-sam/blob/main/services/user-service/tests/handler/get-user-handler.test.ts"
    click EventJson "https://github.com/maoragai12/nx-aws-sam/blob/main/services/user-service/event.json"
    click EnvSvcTemplate "https://github.com/maoragai12/nx-aws-sam/blob/main/services/user-service/.env.template.json"
    click JestSvcConfig "https://github.com/maoragai12/nx-aws-sam/blob/main/services/user-service/jest.config.js"

    %% Styles
    classDef dev fill:#dddddd,stroke:#333,stroke-width:1px
    classDef monorepo fill:#a8c8ff,stroke:#333,stroke-width:1px
    classDef ci fill:#cccccc,stroke:#333,stroke-width:1px
    classDef awsInfra fill:#ffcc99,stroke:#333,stroke-width:1px
    classDef data fill:#99cc99,stroke:#333,stroke-width:1px
```
