Architecture Diagrams - sandhya1631/agentic-paper-trader GitHub Wiki

Architecture Diagrams

This page documents the container architecture, backend components, deployment environment, and agent decision sequence for the Agentic Paper Trader.

1. C4 Level 1: System Context Diagram

The System Context Diagram presents the highest-level view of the Agentic Paper Trader. It shows the people who use the system and the external software systems with which it communicates. Internal implementation components such as FastAPI, Next.js, PostgreSQL, Redis, and Celery are intentionally excluded from this level.

flowchart LR
    Operator["Operator<br/>[Person]<br/>Configures the trading agent,<br/>monitors activity and controls execution"]

    Auditor["Auditor<br/>[Person]<br/>Reviews decisions, policy results,<br/>orders and audit history"]

    APT["Agentic Paper Trader<br/>[Software System]<br/>Uses live market data and an LLM<br/>to propose paper trades, enforce<br/>deterministic risk policies and<br/>execute approved orders"]

    Alpaca["Alpaca<br/>[External Software System]<br/>Provides market data, account information<br/>and paper-trading operations"]

    LLM["Cloud LLM Provider<br/>[External Software System]<br/>Evaluates bounded market context<br/>and returns a structured DecisionProposal"]

    GitHubActions["GitHub Actions<br/>[External Supporting System]<br/>Runs linting, automated tests,<br/>security checks and container builds"]

    Operator -->|"Configures agents, triggers cycles,<br/>reviews results and activates kill switch"| APT

    Auditor -->|"Reviews snapshots, decisions,<br/>policy evidence and order history"| APT

    APT -->|"Requests market clock, bars,<br/>quotes, balances and positions"| Alpaca

    Alpaca -->|"Returns market data,<br/>account state and order status"| APT

    APT -->|"Submits policy-approved<br/>paper orders only"| Alpaca

    APT -->|"Sends bounded AgentContext<br/>without broker credentials"| LLM

    LLM -->|"Returns structured<br/>BUY, SELL or HOLD proposal"| APT

    GitHubActions -->|"Validates proposed<br/>software changes"| APT

    classDef person fill:#12304a,color:#ffffff,stroke:#12304a,stroke-width:2px
    classDef system fill:#2878b5,color:#ffffff,stroke:#12304a,stroke-width:3px
    classDef external fill:#eeeeee,color:#17232d,stroke:#667681,stroke-width:2px
    classDef supporting fill:#eef0ff,color:#17232d,stroke:#6554c0,stroke-width:2px

    class Operator,Auditor person
    class APT system
    class Alpaca,LLM external
    class GitHubActions supporting
Loading

Diagram Elements

Element C4 Type Responsibility
Operator Person Configures the agent, triggers cycles, reviews results and controls execution
Auditor Person Reviews decision history, policy evidence, orders and audit records
Agentic Paper Trader Software System Produces trade proposals, applies risk policies and coordinates approved paper orders
Alpaca External Software System Provides live market data, account information and paper-trading operations
Cloud LLM Provider External Software System Returns a structured BUY, SELL, or HOLD proposal
GitHub Actions External Supporting System Runs automated validation for software changes

Relationship and Color Legend

  • Dark blue: Human actor
  • Blue: Agentic Paper Trader system being developed
  • Gray: External runtime system
  • Purple: External development-support system
  • Arrow direction: Direction of the request or information exchange
  • Arrow label: Describes the information or operation exchanged

System Boundary

The Agentic Paper Trader is treated as one complete software system at C4 Level 1. Its internal applications and data stores are shown separately in the C4 Level 2 Container Diagram.

The LLM cannot submit orders directly. It only returns a structured proposal to the Agentic Paper Trader. The system applies deterministic risk policies before sending any order to the Alpaca Paper Trading API.

2. C4 Level 2: Container Diagram

flowchart LR
    Operator["Operator<br/>[Person]<br/>Configures and monitors the agent"]

    Auditor["Auditor<br/>[Person]<br/>Reviews decisions, policies<br/>and order history"]

    subgraph APT["Agentic Paper Trader - System Boundary"]
        Web["Web Application<br/>[Next.js Container]<br/>Dashboard, settings, approvals,<br/>audit timeline and controls"]

        API["API Application<br/>[FastAPI Container]<br/>Authentication, Fast / REST API,<br/>configuration and live updates"]

        Worker["Agent Worker<br/>Runs market analysis, agent reasoning<br/>and execution cycles"]

        Scheduler["Scheduler<br/>Requests an agent cycle<br/>every 15 minutes"]

        DB[("PostgreSQL<br/>[Database Container]<br/>Users, configuration, snapshots,<br/>decisions, policies, orders and audit")]

        Redis[("Redis<br/>[Data Store Container]<br/>Task queue, distributed locks<br/>and short-lived cache")]
    end

    Alpaca["Alpaca<br/>[External System]<br/>Market Data API and<br/>Paper Trading API"]

    LLM["Cloud LLM Provider<br/>[External System]<br/>Returns a structured<br/>DecisionProposal"]

    Operator -->|"Uses through HTTPS"| Web
    Auditor -->|"Reviews audit information through HTTPS"| Web

    Web -->|"REST API and WebSocket"| API

    API -->|"Creates manual cycle task"| Redis
    Scheduler -->|"Creates scheduled cycle task"| Redis
    Redis -->|"Delivers cycle task"| Worker

    API -->|"Reads and writes configuration"| DB
    API -->|"Reads portfolio and audit data"| DB
    Worker -->|"Stores snapshots, decisions and audit events"| DB

    Worker -->|"Acquires distributed cycle lock"| Redis

    Worker -->|"Requests bars, quotes and account state"| Alpaca
    Alpaca -->|"Returns market and account information"| Worker

    Worker -->|"Submits approved paper orders only"| Alpaca
    Alpaca -->|"Returns order status and fills"| Worker

    Worker -->|"Sends bounded AgentContext"| LLM
    LLM -->|"Returns BUY, SELL or HOLD proposal"| Worker

    classDef person fill:#12304a,color:#ffffff,stroke:#12304a,stroke-width:2px
    classDef application fill:#ddf3fa,color:#17232d,stroke:#2878b5,stroke-width:2px
    classDef worker fill:#e4f5f0,color:#17232d,stroke:#138a80,stroke-width:2px
    classDef datastore fill:#f5f8fa,color:#17232d,stroke:#e98a25,stroke-width:2px
    classDef external fill:#eeeeee,color:#17232d,stroke:#667681,stroke-width:2px

    class Operator,Auditor person
    class Web,API application
    class Worker,Scheduler worker
    class DB,Redis datastore
    class Alpaca,LLM external
Loading

Container Responsibilities

Container Technology Responsibility
Web Application Next.js 15.x Dashboard, settings, approvals, controls and audit timeline
API Application FastAPI 0.115.x Authentication, authorization, configuration and API communication
Agent Worker Celery 5.4.x Market analysis, LLM proposals, policy validation and broker coordination
Scheduler Celery Beat 5.4.x Starts autonomous cycles every 15 minutes
PostgreSQL PostgreSQL 16.x Authoritative application and audit database
Redis Redis 7.x Celery queue and distributed locks
Alpaca External API Market data and paper-broker operations
Cloud LLM External API Structured decision proposals

3. C4 Level 3: Backend Component Diagram

flowchart LR
    Dashboard["Web Application<br/>Next.js Dashboard"]

    subgraph Backend["FastAPI API and Agent Worker - Backend Boundary"]
        ControlAPI["Control API<br/>[Component]<br/>Authentication, settings,<br/>trigger, approval and kill switch"]

        Orchestrator["Agent Orchestrator<br/>[Component]<br/>Coordinates the complete<br/>decision-cycle state machine"]

        MarketService["Market Service<br/>[Component]<br/>Retrieves bars, quotes,<br/>account state and positions"]

        IndicatorService["Indicator Service<br/>[Component]<br/>Calculates RSI-14<br/>and SMA-20/50"]

        ContextBuilder["Context Builder<br/>[Component]<br/>Creates a versioned and<br/>token-bounded AgentContext"]

        LLMAdapter["LLM Adapter<br/>[Component]<br/>Calls the configured model and<br/>validates structured output"]

        PolicyEngine["Policy Engine<br/>[Component]<br/>Evaluates deterministic<br/>risk policies P-001 to P-015"]

        ApprovalService["Approval Service<br/>[Component]<br/>Manages optional operator<br/>approval and expiration"]

        BrokerGateway["Broker Gateway<br/>[Component]<br/>Submits, reconciles and cancels<br/>Alpaca paper orders"]

        Repository["Repositories and Outbox<br/>[Component]<br/>Transactional persistence<br/>and reliable event publication"]
    end

    Database[("PostgreSQL<br/>Authoritative Database")]

    Alpaca["Alpaca APIs<br/>Market Data and Paper Trading"]

    LLM["Cloud LLM Provider<br/>Structured-output API"]

    Dashboard -->|"Authenticated API request"| ControlAPI
    ControlAPI -->|"Trigger, configure or approve"| Orchestrator

    Orchestrator -->|"Request authoritative state"| MarketService

    MarketService -->|"Request bars, quotes, clock and account"| Alpaca
    Alpaca -->|"Return market and account data"| MarketService

    MarketService -->|"Validated completed bars"| IndicatorService
    IndicatorService -->|"RSI and SMA values"| ContextBuilder
    MarketService -->|"Account, positions and open orders"| ContextBuilder

    ContextBuilder -->|"Versioned AgentContext"| LLMAdapter

    LLMAdapter -->|"Structured model request"| LLM
    LLM -->|"DecisionProposal"| LLMAdapter

    LLMAdapter -->|"Schema-validated proposal"| Orchestrator

    Orchestrator -->|"Proposal and authoritative state"| PolicyEngine

    PolicyEngine -->|"Allowed proposal"| ApprovalService
    PolicyEngine -->|"Denied proposal and policy evidence"| Repository

    ApprovalService -->|"ApprovedOrder"| BrokerGateway
    ApprovalService -->|"Rejected or expired decision"| Repository

    BrokerGateway -->|"Approved paper order only"| Alpaca
    Alpaca -->|"Order ID, status and fills"| BrokerGateway

    Orchestrator -->|"Cycle state transitions"| Repository
    BrokerGateway -->|"Order result"| Repository

    Repository -->|"SQL transaction"| Database

    classDef interface fill:#ddf3fa,color:#17232d,stroke:#2878b5,stroke-width:2px
    classDef control fill:#ddf3fa,color:#17232d,stroke:#2878b5,stroke-width:2px
    classDef orchestration fill:#e4f5f0,color:#17232d,stroke:#138a80,stroke-width:2px
    classDef policy fill:#fff1de,color:#17232d,stroke:#e98a25,stroke-width:2px
    classDef execution fill:#fbe7e5,color:#17232d,stroke:#c84b41,stroke-width:2px
    classDef datastore fill:#f5f8fa,color:#17232d,stroke:#667681,stroke-width:2px
    classDef external fill:#eeeeee,color:#17232d,stroke:#667681,stroke-width:2px

    class Dashboard interface
    class ControlAPI,MarketService,IndicatorService,ContextBuilder,Repository control
    class Orchestrator orchestration
    class LLMAdapter,PolicyEngine,ApprovalService policy
    class BrokerGateway execution
    class Database datastore
    class Alpaca,LLM external
Loading

Safety Boundary

The LLM cannot communicate directly with the Broker Gateway.

Every executable proposal must pass through:

  1. Schema validation
  2. Agent Orchestrator
  3. Deterministic Policy Engine
  4. Optional human approval
  5. Final kill-switch and account-state validation
  6. Broker Gateway

Only an ApprovedOrder can reach Alpaca Paper Trading.

4. Deployment Diagram

flowchart LR
    Browser["User Browser<br/>Runs the Next.js client"]

    subgraph DockerHost["Docker Compose Host / Course VM"]
        Frontend["Frontend Container<br/>Next.js 15.x<br/>Port 3000"]

        API["API Container<br/>FastAPI 0.115.x<br/>Port 8000"]

        Worker["Worker Container<br/>Celery 5.4.x<br/>Agent decision cycles"]

        Beat["Scheduler Container<br/>Celery Beat 5.4.x<br/>15-minute triggers"]

        Postgres[("PostgreSQL Container<br/>PostgreSQL 16.x<br/>Persistent volume")]

        Redis[("Redis Container<br/>Redis 7.x<br/>Queue and locks")]
    end

    Alpaca["Alpaca Cloud<br/>Market Data API and<br/>Paper Trading API"]

    ModelProvider["Cloud LLM Provider<br/>Structured-output HTTPS API"]

    GitHubActions["GitHub Actions<br/>Linting, tests,<br/>security checks and builds"]

    Browser -->|"HTTPS"| Frontend
    Frontend -->|"REST API and WebSocket"| API

    API -->|"Publish manual task"| Redis
    Beat -->|"Publish scheduled task"| Redis
    Redis -->|"Deliver cycle task"| Worker

    API -->|"Async SQL"| Postgres
    Worker -->|"Async SQL and audit records"| Postgres

    Worker -->|"HTTPS market and account requests"| Alpaca
    Worker -->|"HTTPS approved paper orders"| Alpaca

    Worker -->|"HTTPS bounded AgentContext"| ModelProvider
    ModelProvider -->|"Structured DecisionProposal"| Worker

    GitHubActions -->|"Build and validate"| Frontend
    GitHubActions -->|"Build and validate"| API
    GitHubActions -->|"Build and validate"| Worker

    classDef client fill:#ddf3fa,color:#17232d,stroke:#2878b5,stroke-width:2px
    classDef application fill:#ddf3fa,color:#17232d,stroke:#2878b5,stroke-width:2px
    classDef worker fill:#e4f5f0,color:#17232d,stroke:#138a80,stroke-width:2px
    classDef datastore fill:#f5f8fa,color:#17232d,stroke:#e98a25,stroke-width:2px
    classDef external fill:#eeeeee,color:#17232d,stroke:#667681,stroke-width:2px
    classDef cicd fill:#eef0ff,color:#17232d,stroke:#6554c0,stroke-width:2px

    class Browser client
    class Frontend,API application
    class Worker,Beat worker
    class Postgres,Redis datastore
    class Alpaca,ModelProvider external
    class GitHubActions cicd
Loading

Deployment Notes

  • The course MVP runs with Docker Compose.
  • It may run on a developer computer or one course VM.
  • PostgreSQL uses a persistent Docker volume.
  • Redis is temporary infrastructure and is not the authoritative record.
  • External communication uses HTTPS.
  • Alpaca credentials are available only to trusted backend components.
  • Kubernetes and real-money infrastructure are outside the MVP scope.

5. Agent Decision Sequence

sequenceDiagram
    autonumber

    participant Scheduler
    participant Agent as Agent Layer
    participant LLM
    participant Policy
    participant Broker as Paper Broker

    Scheduler->>Agent: Start cycle
    Agent->>LLM: Send structured context
    LLM-->>Agent: Return action proposal
    Agent->>Policy: Validate proposal
    Policy-->>Agent: Allow or deny

    alt Proposal allowed
        Agent->>Broker: Submit paper order
        Broker-->>Agent: Return order result
    else Proposal denied
        Agent->>Agent: Record rejection
    end

    Agent-->>Scheduler: Publish cycle result
Loading

Sequence Summary

  1. The Scheduler starts a trading cycle.
  2. The Agent sends structured market context to the LLM.
  3. The LLM returns a BUY, SELL, or HOLD proposal.
  4. The Policy layer validates the proposal.
  5. An allowed proposal is submitted to the Paper Broker.
  6. A denied proposal is rejected without contacting the broker.
  7. The Agent publishes the final cycle result.
⚠️ **GitHub.com Fallback** ⚠️