C4 Architectural Blueprints

C4 Level 2: Container Decomposition

Decomposes the internal containers powering the system: the Web UI console, the Spring Boot 4.1.x microservices backend, and the PostgreSQL 17 relational database.

flowchart TB
    Operator["👤 Operator / Founder
[Browser User]"]

    subgraph FBA ["FBA Automator Architecture Containers"]
        direction TB
        WebApp["💻 Web Operations Console
[HTML5 / Vanilla JS / React Components]
Single-page interface with 145+ module panels"]
        Backend["☕ Spring Boot Backend Application
[Java 25 LTS / Spring Boot 4.1.x]
Financial math (BigDecimal), schedulers, REST controllers"]
        Database[("🗄️ PostgreSQL Master Database
[PostgreSQL 17]
Persists state across 145+ relational tables")]
    end

    subgraph ExtIntegrations ["External Cloud APIs"]
        SPAPI2["Amazon SP-API"]
        AdsAPI2["Amazon Ads API"]
        Keepa2["Keepa Data API"]
        Discord2["Discord Symmetrical Webhooks"]
    end

    Operator -->|"Interacts via UI"| WebApp
    WebApp -->|"JSON / REST APIs (Port 8080)"| Backend
    Backend -->|"JPA / Hibernate (Port 5432)"| Database
    Backend -->|"SP-API Orders & Inbound"| SPAPI2
    Backend -->|"Hourly Bid Multipliers"| AdsAPI2
    Backend -->|"Historical BSR / Prices"| Keepa2
    Backend -->|"Webhooks"| Discord2

    style WebApp fill:#0369a1,stroke:#38bdf8,stroke-width:2px,color:#fff
    style Backend fill:#047857,stroke:#34d399,stroke-width:2px,color:#fff
    style Database fill:#4338ca,stroke:#818cf8,stroke-width:2px,color:#fff
                    

Structurizr DSL Specification

Source of truth definition stored in architecture/workspace.dsl:

workspace "Sammoho FBA Automator" "Enterprise Architecture C4 Model for the Sammoho Amazon FBA Automator Suite." {

    model {
        operator = person "Operator / Founder" "Manages Amazon FBA inventory, procurement, PPC, pricing, and brand protection operations." "Founder"

        fbaSystem = softwareSystem "FBA Supply Chain Automator" "Autonomous enterprise Amazon FBA operations, procurement, multi-channel velocity, and compliance platform." {
            webApp = container "Web Operations Console" "Delivers single-page responsive dashboards, 145+ module control panels, and interactive operational studios." "HTML5 / Vanilla JS / React UI Components" "Web App"
            backendApp = container "Spring Boot Backend Application" "Executes financial math, deterministic fee tier algorithms, automated schedulers, and RESTful API endpoints." "Java 25 LTS / Spring Boot 4.1.x / Jakarta EE 11" "Backend Service"
            database = container "PostgreSQL Master Database" "Persists transactional and relational state across 145+ operational tables (procurement, inventory, pricing, brand protection)." "PostgreSQL 17 Relational Database" "Database"
        }

        cloudflareTunnel = softwareSystem "Cloudflare Zero Trust Tunnel" "Secure encrypted reverse proxy and email PIN authentication wall protecting ops.sammoho.com." "External Service"
        amazonSpApi = softwareSystem "Amazon Selling Partner API (SP-API)" "Official Amazon REST API for catalog items, inbound shipments, FBA inventory, and orders." "External Service"
        amazonAdsApi = softwareSystem "Amazon Advertising API" "Programmatic Sponsored Products campaigns, dayparting bid multipliers, and ad group metrics." "External Service"
        keepaApi = softwareSystem "Keepa Data API" "Historical Best Seller Rank (BSR), Buy Box price tracking, and competitor sales velocity data." "External Service"
        shipbobWms = softwareSystem "ShipBob 3PL WMS" "Omnichannel warehouse fulfillment, carrier tracking, and external pallet receiving." "External Service"
        discordWebhooks = softwareSystem "Discord Operations Server" "Real-time symmetrical notification channels for procurement milestones, stockouts, and legal notices." "External Service"
        geminiAi = softwareSystem "Google Gemini 2.5 Flash AI" "Voice-of-Customer review sentiment extraction, bilingual factory translation, and listing copy optimization." "External Service"

        # Relationships
        operator -> cloudflareTunnel "Accesses ops.sammoho.com with Email PIN verification" "HTTPS / TLS 1.3"
        cloudflareTunnel -> webApp "Routes authenticated HTTP requests to front-end assets" "HTTP / Port 8080"
        operator -> webApp "Navigates module panels, submits operational actions, reviews P&L" "Browser"
        webApp -> backendApp "Dispatches REST API requests with X-Operator-Key auth" "JSON / REST"
        backendApp -> database "Reads and writes transactional entities via Hibernate / JPA" "JDBC / PostgreSQL Driver"

        backendApp -> amazonSpApi "Syncs inventory levels, submits inbound plans, tracks FBA shipments" "REST / LWA OAuth 2.0"
        backendApp -> amazonAdsApi "Pushes hourly dayparting bids and target ACOS rules" "REST / Amazon Ads API"
        backendApp -> keepaApi "Queries ASIN price history and competitor Buy Box rotation" "REST / HTTPS"
        backendApp -> shipbobWms "Dispatches MCF fulfillment orders and ingests tracking webhooks" "REST / HMAC Webhooks"
        backendApp -> discordWebhooks "Dispatches automated operational embeds to live/sandbox channels" "HTTPS Webhooks"
        backendApp -> geminiAi "Sends review text and prompts for sentiment analysis and CAPA drafts" "REST / Gemini API"
    }

    views {
        systemContext fbaSystem "SystemContext" "High-level System Context diagram for the FBA Automator platform." {
            include *
            autoLayout lr
        }

        container fbaSystem "Containers" "Container architecture diagram illustrating internal Spring Boot, React/HTML, and PostgreSQL components." {
            include *
            autoLayout tb
        }
    }
}