# aaronshaf/dynamodb-admin architecture

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

- Interactive diagram: https://gitdiagram.com/aaronshaf/dynamodb-admin
- Repository: https://github.com/aaronshaf/dynamodb-admin

## Overview

##### Project Type and Purpose
- This is a full-stack CLI/web application written in TypeScript that provides a graphical user interface for managing a local or in-memory DynamoDB instance (DynamoDB Local, dynalite, localstack, etc.).
- The README describes both a global CLI mode and an embeddable library mode; core functionality is to serve HTML/CSS/JS to a browser, handle HTTP requests, and proxy those requests to a DynamoDB endpoint via the AWS SDK v3.

##### File Structure Analysis
- bin/
- Entry point script (`dynamodb-admin.ts`) that parses CLI args or environment variables, configures the DynamoDB client, and starts the server.
- lib/
- `backend.ts`: sets up and configures the Express/Koa-like server (middleware, view engine, static assets).
- `routes.ts`: defines HTTP routes for listing tables, creating tables, getting items, scanning, purging, etc.
- actions/: each file implements a specific DynamoDB operation (getPage, listAllTables, purgeTable).
- `dynamoDbApi.ts`: wraps AWS SDK v3 calls in a uniform interface.
- util.ts, utils/asyncMiddleware.ts: helper functions for error-handling, key parsing, etc.
- types.d.ts: shared TypeScript definitions.
- public/: static assets (CSS themes, vendor JS for ACE editor or Bootstrap).
- views/: EJS templates for server-side rendering—table lists, create-table form, item views, error display, partials (layout, breadcrumbs).
- Configuration and build:
- rollup.config.ts and tsconfig.json for bundling and TS compilation.
- nodemon.json, Dockerfile, GitHub Actions workflows for CI/Publishing.

##### Key Technologies and Patterns
- Node.js + TypeScript
- Express-style server (middleware pattern)
- AWS SDK v3 DynamoDBClient
- Server-side rendering with EJS templates
- CLI args & environment variables for configuration
- Modular “actions” layer encapsulating database operations
- MVC-like separation: views (EJS) ↔ routes (controller) ↔ actions (model)

##### Main Components and Relationships
a. Client (Browser)
- Consumes HTML/CSS/JS served from the app’s public/ and views/
- Initiates HTTP requests to the server (GET /tables, POST /create, GET /items/:key, etc.)
b. Server (Node.js App)
- Entry Point (bin/dynamodb-admin.ts) → config & instantiate DynamoDBClient → createServer()
- HTTP Server (lib/backend.ts)
– Middleware (async error handling, static assets, request parsing)
– Routes (lib/routes.ts) map endpoints to action handlers
– View Engine (EJS) renders templates in response
c. Action Layer (lib/actions/*.ts)
- Each action calls dynamoDbApi to perform a specific DynamoDB operation
d. Data Layer (lib/dynamoDbApi.ts)
- Wraps AWS SDK v3 DynamoDBClient commands
- Configuration (lib/config.ts) reads endpoint, credentials, region
e. DynamoDB Endpoint
- Local DynamoDB, dynalite, localstack or remote AWS instance

##### Architectural Patterns / Principles
- Single-process monolith with clear modular decomposition
- MVC (Views + Controllers/Routes + Model/Action layer)
- Dependency Injection: server creation accepts a preconfigured DynamoDBClient
- Separation of concerns: action handlers contain business logic, routes only wire HTTP to actions, views only handle presentation

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Client Side"
        Client["Browser UI"]:::client
        DarkTheme["dark-theme.css"]:::client
        Vendor["vendor (JS/CSS libs)"]:::client
    end

    subgraph "Server Application"
        CLI["CLI Entry Point\nbin/dynamodb-admin.ts"]:::server
        Config["Configuration Reader\nlib/config.ts"]:::server

        subgraph "Server Layer"
            Server1["HTTP Server Setup\nlib/backend.ts"]:::server

            subgraph "Utilities & Types"
                Util["util.ts"]:::server
                Async["asyncMiddleware.ts"]:::server
                Types["types.d.ts"]:::server
            end

            subgraph "View Layer"
                CreateTable["create-table.ejs"]:::server
                GetView["get.ejs"]:::server
                ItemView["item.ejs"]:::server
                MetaView["meta.ejs"]:::server
                ScanView["scan.ejs"]:::server
                TablesView["tables.ejs"]:::server
                Partials["partials/"]:::server
            end

            subgraph "Request Handling"
                Routes["Routes (Controllers)\nlib/routes.ts"]:::server
            end

            subgraph "Action Layer"
                getPage["getPage.ts"]:::server
                listAll["listAllTables.ts"]:::server
                purgeTable["purgeTable.ts"]:::server
            end

            DataWrapper["Data Access Wrapper\nlib/dynamoDbApi.ts"]:::data
            AWS["AWS SDK v3 DynamoDBClient"]:::data
        end
    end

    DynamoEndpoint["DynamoDB Endpoint\n(Local / dynalite / AWS)"]:::external

    %% Connections
    CLI -->|config loads| Config
    Config --> Server1
    Server1 --> Util
    Server1 --> Async
    Server1 --> Types
    Server1 --> CreateTable
    Server1 --> GetView
    Server1 --> ItemView
    Server1 --> MetaView
    Server1 --> ScanView
    Server1 --> TablesView
    Server1 --> Partials
    Server1 --> DarkTheme
    Server1 --> Vendor
    Client -->|requests| Server1

    Server1 -->|handles requests| Routes
    Routes -->|invoke| getPage
    Routes -->|invoke| listAll
    Routes -->|invoke| purgeTable
    getPage --> DataWrapper
    listAll --> DataWrapper
    purgeTable --> DataWrapper
    DataWrapper --> AWS
    AWS -->|connects to| DynamoEndpoint

    %% Click Events
    click CLI "https://github.com/aaronshaf/dynamodb-admin/blob/master/bin/dynamodb-admin.ts"
    click Config "https://github.com/aaronshaf/dynamodb-admin/blob/master/lib/config.ts"
    click Server1 "https://github.com/aaronshaf/dynamodb-admin/blob/master/lib/backend.ts"
    click Util "https://github.com/aaronshaf/dynamodb-admin/blob/master/lib/util.ts"
    click Async "https://github.com/aaronshaf/dynamodb-admin/blob/master/lib/utils/asyncMiddleware.ts"
    click Types "https://github.com/aaronshaf/dynamodb-admin/blob/master/lib/types.d.ts"
    click Routes "https://github.com/aaronshaf/dynamodb-admin/blob/master/lib/routes.ts"
    click getPage "https://github.com/aaronshaf/dynamodb-admin/blob/master/lib/actions/getPage.ts"
    click listAll "https://github.com/aaronshaf/dynamodb-admin/blob/master/lib/actions/listAllTables.ts"
    click purgeTable "https://github.com/aaronshaf/dynamodb-admin/blob/master/lib/actions/purgeTable.ts"
    click DataWrapper "https://github.com/aaronshaf/dynamodb-admin/blob/master/lib/dynamoDbApi.ts"
    click DarkTheme "https://github.com/aaronshaf/dynamodb-admin/blob/master/public/css/dark-theme.css"
    click Vendor "https://github.com/aaronshaf/dynamodb-admin/tree/master/public/vendor/"
    click CreateTable "https://github.com/aaronshaf/dynamodb-admin/blob/master/views/create-table.ejs"
    click GetView "https://github.com/aaronshaf/dynamodb-admin/blob/master/views/get.ejs"
    click ItemView "https://github.com/aaronshaf/dynamodb-admin/blob/master/views/item.ejs"
    click MetaView "https://github.com/aaronshaf/dynamodb-admin/blob/master/views/meta.ejs"
    click ScanView "https://github.com/aaronshaf/dynamodb-admin/blob/master/views/scan.ejs"
    click TablesView "https://github.com/aaronshaf/dynamodb-admin/blob/master/views/tables.ejs"
    click Partials "https://github.com/aaronshaf/dynamodb-admin/tree/master/views/partials/"

    %% Styles
    classDef client fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef server fill:#90EE90,stroke:#333,stroke-width:1px
    classDef data fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#FF6347,stroke:#333,stroke-width:1px
```
