# americanexpress/one-app architecture

> Architecture diagram of the GitHub repository americanexpress/one-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/americanexpress/one-app
- Repository: https://github.com/americanexpress/one-app

## Overview

##### Main Components
- Node.js Server: This is implemented in the src/server directory. It handles server side rendering (SSR), API endpoints, middleware (e.g., security headers, CORS, logging), and configuration management.
- Client Application: Located in src/client, this contains the entry points for client-side rendering, service-worker code (with polyfills and lifecycle events), and publicPath settings.
- Holocron / Modular System: The system’s modular nature is reflected in how the “root module” (the entry point) loads other independent modules. Sample modules and versioned module folders in the prod-sample and one-app-statics directories, as well as the scripts for bundling (one-app-bundler), illustrate these dynamics.
- Universal/Shared Components: Code in src/universal (including reducers, routes, and ducks) that is used on both the client and server.
- Performance, Testing & CI/CD Infrastructure: The presence of directories like __performance__, __tests__, and various GitHub workflow configurations indicates automated testing, performance monitoring, and continuous integration/delivery processes.
- Static Assets & Deployment: The one-app-statics directory, Docker setups (Dockerfile, docker-compose files), and production samples hint at how modules and assets are bundled and served (possibly via a local dev CDN).

##### Relationships & Data Flows
- Client-to-Server Communication: Show the browser making HTTP requests to the Node.js server. Indicate SSR where the server pre-renders the React application and how the client then takes over hydration.
- Service Worker Interaction: Illustrate the service-worker components (from src/client/service-worker) that handle caching, polyfills, and potentially offline strategies.
- External Dependencies: Include key technologies such as React (for the UI), Node.js (for the server environment), Docker (for containerization), and any monitoring tools (metrics and logging frameworks) visible via directories like src/server/metrics and scripts in __performance__.

##### Architectural Patterns & Design Principles
- Modularity & Extensibility: Emphasize that each Holocron module can be independently developed, tested, and deployed, with a central “module map” coordinating the dynamic loading. Also note the role of the root module as the entry point that orchestrates other modules.
- Reusability Across Contexts: The existence of a universal code layer (src/universal) shows shared logic that operates on both client and server sides, reinforcing the isomorphic design.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Nodes
    Browser("Browser"):::browser

    Server("Node.js Server (SSR, API, Middleware & Plugins)"):::server
    Client("Client Application (React Renderer, Service Worker, Polyfills)"):::client
    Modules("Module Loader / Holocron Modules"):::modular
    StaticAssets("Static Assets & Module Map"):::static
    Universal("Universal/Shared Components"):::shared
    CICD("CI/CD & Testing Infrastructure"):::ci
    DockerSetup("Docker Setup (Dockerfile/Docker Compose)"):::docker

    %% Data Flow Connections
    Browser -->|"HTTP-request"| Server
    Server -->|"SSR/hydrates"| Client
    Server -->|"Fetch-Holocron"| Modules
    Modules -->|"Load-Modules"| Client
    Server -->|"Serve-Assets"| StaticAssets
    Server -->|"Share-Logic"| Universal
    CICD -->|"Pipeline-Triggers"| Server
    CICD -->|"Tests&Perf"| Modules
    DockerSetup -->|"Containerizes"| Server

    %% Click Events
    click Server "https://github.com/americanexpress/one-app/tree/main/src/server"
    click Client "https://github.com/americanexpress/one-app/tree/main/src/client"
    click Modules "https://github.com/americanexpress/one-app/tree/main/prod-sample/sample-modules"
    click StaticAssets "https://github.com/americanexpress/one-app/tree/main/one-app-statics"
    click Universal "https://github.com/americanexpress/one-app/tree/main/src/universal"
    click CICD "https://github.com/americanexpress/one-app/tree/main/.github/workflows"
    click DockerSetup "https://github.com/americanexpress/one-app/tree/main/Dockerfile"

    %% Styles
    classDef server fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef client fill:#ccffcc,stroke:#009900,stroke-width:2px;
    classDef modular fill:#ccccff,stroke:#0000ff,stroke-width:2px;
    classDef static fill:#ffffcc,stroke:#999900,stroke-width:2px;
    classDef shared fill:#e0e0e0,stroke:#666666,stroke-width:2px;
    classDef ci fill:#ffd700,stroke:#cc8c00,stroke-width:2px;
    classDef docker fill:#cceeff,stroke:#007acc,stroke-width:2px;
    classDef browser fill:#ffddcc,stroke:#cc6600,stroke-width:2px;
```
