# abstractplay/node-backend architecture

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

- Interactive diagram: https://gitdiagram.com/abstractplay/node-backend
- Repository: https://github.com/abstractplay/node-backend

## Overview

##### Project type and purpose
- This is a serverless Node.js “backend for AbstractPlay” that exposes a REST-style API via AWS API Gateway and AWS Lambda functions. It uses AWS DynamoDB as its single table data store, and AWS Cognito to manage authentication and authorization. Utility scripts live in a “utils” folder for batch or maintenance jobs, and i18n support is provided via translation JSON files in “locales.”

##### File structure
- Top-level configuration files
- serverless.yml: declares all Lambda functions, HTTP events, DynamoDB table settings, and Cognito authorizer settings
- .github/workflows/…: GitHub Actions that automatically deploy dev and prod on branch commits
- tsconfig.json, package.json, .eslintrc.json: TypeScript, dependency, and lint setups
- “api” directory
- abstractplay.ts: main Lambda handler implementing the REST API routes
- “lib” directory
- Shared helper modules (country code mapping, ISO conversions) compiled from TS to JS
- “utils” directory
- Stand-alone TypeScript scripts for database dumps, record migrations, tournaments, summaries, etc. invoked manually or via cron
- “locales” directory
- i18next JSON files for English, French, Italian used at build time by i18next-parser.config.js
- index.html
- A minimal static file (could be a test page or landing page)

##### README for additional insights
- Cognito user pools for Dev/Prod are configured and referenced in serverless.yml.
- All data lives in a single DynamoDB table with a composite primary key design (pk, sk) implementing many entity-types in one table.
- Utilities and Lambdas use AWS SDK to read/write items according to the single-table schema.
- GitHub Actions trigger deployments automatically on branch pushes.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External client
    Client["Client"]:::external

    %% API Layer
    APIgw["API Gateway"]:::aws
    Cognito["Cognito User Pool"]:::auth

    %% Compute Tier
    subgraph "Compute Tier"
        direction TB
        serverless["serverless.yml\n(Infrastructure as Code)"]:::infra
        subgraph "API Lambdas"
            direction TB
            APILambdas["abstractplay.ts\n(REST API Handler)"]:::lambda
        end
        subgraph "Utility Lambdas"
            direction TB
            DumpDB["dumpdb.ts"]:::lambda
            RecordsManifest["records-manifest.ts"]:::lambda
            RecordsMoveTimes["records-move-times.ts"]:::lambda
            RecordsTTM["records-ttm.ts"]:::lambda
            Records["records.ts"]:::lambda
            StandingChallenges["standingchallenges.ts"]:::lambda
            StartTournaments["starttournaments.ts"]:::lambda
            Summarize["summarize.ts"]:::lambda
            YourTurn["yourturn.ts"]:::lambda
        end
    end

    %% Data Storage
    DynamoDB["DynamoDB\nSingle Table (pk, sk schema)"]:::database

    %% Static Assets
    subgraph "Static Hosting"
        direction TB
        S3CF["S3 / CloudFront"]:::aws
        Index["index.html"]:::infra
    end

    %% Localization & Config
    subgraph "Localization & Config"
        direction TB
        CountryCodeTS["countryCodeList.ts"]:::infra
        CountryCodeJS["countryCodeList.js"]:::infra
        ISOtoCountryTS["isoToCountryCode.ts"]:::infra
        ISOtoCountryJS["isoToCountryCode.js"]:::infra
        ParserConfig["i18next-parser.config.js"]:::infra
        en1["locales/en/apback.json"]:::infra
        en2["locales/en/apback_old.json"]:::infra
        fr["locales/fr/apback.json"]:::infra
        it["locales/it/apback.json"]:::infra
        TSConfig["tsconfig.json"]:::infra
        PackageJSON["package.json"]:::infra
        PackageLock["package-lock.json"]:::infra
        ESLint[".eslintrc.json"]:::infra
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline" 
        direction TB
        GHDev["deploy-dev.js.yml"]:::pipeline
        GHProd["deploy-prod.js.yml"]:::pipeline
    end

    %% Relationships
    Client --> APIgw --> Cognito --> APILambdas
    APILambdas -->|read/write| DynamoDB
    DumpDB -->|batch job| DynamoDB
    RecordsManifest -->|batch job| DynamoDB
    RecordsMoveTimes -->|batch job| DynamoDB
    RecordsTTM -->|batch job| DynamoDB
    Records -->|batch job| DynamoDB
    StandingChallenges -->|batch job| DynamoDB
    StartTournaments -->|batch job| DynamoDB
    Summarize -->|batch job| DynamoDB
    YourTurn -->|batch job| DynamoDB
    Client --> S3CF --> Index
    GHDev -->|deploy| serverless
    GHProd -->|deploy| serverless
    serverless --> APILambdas
    serverless --> DumpDB
    serverless --> RecordsManifest
    serverless --> RecordsMoveTimes
    serverless --> RecordsTTM
    serverless --> Records
    serverless --> StandingChallenges
    serverless --> StartTournaments
    serverless --> Summarize
    serverless --> YourTurn

    %% Click Events
    click serverless "https://github.com/abstractplay/node-backend/blob/main/serverless.yml"
    click APILambdas "https://github.com/abstractplay/node-backend/blob/main/api/abstractplay.ts"
    click DumpDB "https://github.com/abstractplay/node-backend/blob/main/utils/dumpdb.ts"
    click RecordsManifest "https://github.com/abstractplay/node-backend/blob/main/utils/records-manifest.ts"
    click RecordsMoveTimes "https://github.com/abstractplay/node-backend/blob/main/utils/records-move-times.ts"
    click RecordsTTM "https://github.com/abstractplay/node-backend/blob/main/utils/records-ttm.ts"
    click Records "https://github.com/abstractplay/node-backend/blob/main/utils/records.ts"
    click StandingChallenges "https://github.com/abstractplay/node-backend/blob/main/utils/standingchallenges.ts"
    click StartTournaments "https://github.com/abstractplay/node-backend/blob/main/utils/starttournaments.ts"
    click Summarize "https://github.com/abstractplay/node-backend/blob/main/utils/summarize.ts"
    click YourTurn "https://github.com/abstractplay/node-backend/blob/main/utils/yourturn.ts"
    click CountryCodeTS "https://github.com/abstractplay/node-backend/blob/main/lib/countryCodeList.ts"
    click CountryCodeJS "https://github.com/abstractplay/node-backend/blob/main/lib/countryCodeList.js"
    click ISOtoCountryTS "https://github.com/abstractplay/node-backend/blob/main/lib/isoToCountryCode.ts"
    click ISOtoCountryJS "https://github.com/abstractplay/node-backend/blob/main/lib/isoToCountryCode.js"
    click ParserConfig "https://github.com/abstractplay/node-backend/blob/main/i18next-parser.config.js"
    click en1 "https://github.com/abstractplay/node-backend/blob/main/locales/en/apback.json"
    click en2 "https://github.com/abstractplay/node-backend/blob/main/locales/en/apback_old.json"
    click fr "https://github.com/abstractplay/node-backend/blob/main/locales/fr/apback.json"
    click it "https://github.com/abstractplay/node-backend/blob/main/locales/it/apback.json"
    click TSConfig "https://github.com/abstractplay/node-backend/blob/main/tsconfig.json"
    click PackageJSON "https://github.com/abstractplay/node-backend/blob/main/package.json"
    click PackageLock "https://github.com/abstractplay/node-backend/blob/main/package-lock.json"
    click ESLint "https://github.com/abstractplay/node-backend/blob/main/.eslintrc.json"
    click GHDev "https://github.com/abstractplay/node-backend/blob/main/.github/workflows/deploy-dev.js.yml"
    click GHProd "https://github.com/abstractplay/node-backend/blob/main/.github/workflows/deploy-prod.js.yml"

    %% Styles
    classDef external fill:#afe,stroke:#333,stroke-width:1px
    classDef aws fill:#fdd,stroke:#333,stroke-width:1px
    classDef lambda fill:#cdf,stroke:#333,stroke-width:1px
    classDef database fill:#fdc,stroke:#333,stroke-width:1px
    classDef auth fill:#dfd,stroke:#333,stroke-width:1px
    classDef pipeline fill:#ddd,stroke:#666,stroke-dasharray:5 5
    classDef infra fill:#eef,stroke:#333,stroke-width:1px
```
