# ygwyg/mahoraga architecture

> Architecture diagram of the GitHub repository ygwyg/mahoraga, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ygwyg/mahoraga
- Repository: https://github.com/ygwyg/mahoraga

## Overview

##### Project type and purpose
- MAHORAGA is a full-stack, serverless trading application with two major surfaces:
- A Cloudflare-hosted backend (Workers + Durable Objects) that runs a 24/7 LLM-powered trading agent.
- A React-based dashboard for monitoring, configuration, and manual triggers.
- It ingests sentiment data (StockTwits, Reddit, Twitter), runs LLM analysis (OpenAI, Anthropic, Google, xAI, DeepSeek), applies trading strategies, and places orders via Alpaca. Persistent state is stored in D1, KV, and R2.

##### File structure
- Top level:
- src/ — Worker code
– index.ts: entrypoint, HTTP router (/agent/*, /mcp, /jobs/cron)
– durable-objects/mahoraga-harness.ts: the core stateful trading loop
– durable-objects/session.ts: session management
– jobs/cron.ts: periodic wake-ups for data gathering/trading
– providers/: connectors to external APIs (Alpaca, LLMs, social news)
– policy/: validation and approval logic
– mcp/: tool-access server
– storage/: abstraction over D1 (relational), KV (cache), R2 (artifacts)
– strategy/: gatherers, rules, prompts defining the trading logic
– core/: orchestration (policy-broker, types, utils)
- migrations/: SQL scripts to initialize D1 schema
- dashboard/: React app (Vite + TypeScript) for UI
- docs/: static HTML guides
- wrangler.jsonc: Cloudflare Workers configuration
- Config files: .env.example, agent-config.example.json, biome.json
- Build/test: tsconfig.json, vitest.config.ts, GitHub Actions workflow (ci.yml)

##### Key insights from the README
- Deployment targets: Cloudflare Workers, D1 (SQLite), KV, R2
- External integrations: StockTwits, Reddit, Twitter, Alpaca, LLM providers via raw OpenAI, AI SDK, or Cloudflare AI Gateway
- Authentication: Bearer tokens for API, kill-switch secret
- Features: cron-driven gathering, durable-object state, policy engine, staleness detection, Discord webhooks, pre-market analysis

##### Diagramming recommendations
- Frontend (e.g., blue)
- Serverless runtime (e.g., green)
- Storage (e.g., orange)
- External services (e.g., gray)

##### Essential elements
- Durable Object is central, as it orchestrates strategy, policy, providers, and storage.
- Don’t forget the cron scheduler as a trigger source.
- LLM provider decision—raw vs SDK vs gateway—as one configurable adapter.
- Surface the MCP server as a utility endpoint separate from the core agent API.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        Dashboard["React Dashboard"]:::frontend
    end

    %% Serverless Runtime
    subgraph "Serverless Runtime" 
        direction TB
        HTTP["Cloudflare Workers HTTP Layer"]:::compute
        Cron["Cron Scheduler"]:::compute
        subgraph "Durable Objects"
            direction TB
            Mahoraga["MahoragaHarness Durable Object"]:::compute
            Session["Session Durable Object"]:::compute
        end
    end

    %% Adapter Layer
    subgraph "Provider Adapters" 
        direction TB
        Alpaca["Alpaca Trading API Adapter"]:::adapter
        LLM["LLM Gateways Adapter"]:::adapter
        Social["Social Data Adapter"]:::adapter
        News["News & Scraper Adapter"]:::adapter
    end

    %% Core & Logic
    subgraph "Core & Strategy"
        direction TB
        Policy["Policy Engine"]:::compute
        Strategy["Strategy Modules"]:::compute
        MCP["MCP Server"]:::compute
    end

    %% Storage Tier
    subgraph "Storage Tier"
        direction TB
        D1["D1 Database (SQL)"]:::storage
        KV["KV Namespace (Cache)"]:::storage
        R2["R2 Bucket (Artifacts)"]:::storage
    end

    %% External Services
    subgraph "External Services"
        direction TB
        StockTwits["StockTwits"]:::external
        Reddit["Reddit"]:::external
        Twitter["Twitter"]:::external
        OpenAI["OpenAI"]:::external
        AI_SDK["AI SDK"]:::external
        CFGW["Cloudflare AI Gateway"]:::external
        AlpacaAPI["Alpaca API"]:::external
        Discord["Discord Webhook"]:::external
        EDGAR["SEC-EDGAR"]:::external
    end

    %% Connections
    Dashboard -->|"HTTPS"| HTTP
    HTTP -->|"forwards requests"| Mahoraga
    Cron -->|"tick events"| Mahoraga
    Mahoraga -->|"session calls"| Session
    Mahoraga -->|"reads/writes"| D1
    Mahoraga -->|"KV GET/PUT"| KV
    Mahoraga -->|"R2 PUT/GET"| R2
    Mahoraga -->|"invoke"| Alpaca
    Mahoraga -->|"invoke"| LLM
    Mahoraga -->|"invoke"| Social
    Mahoraga -->|"invoke"| News
    Mahoraga -->|"notify"| Discord
    MCP -->|"tool-access"| Mahoraga
    MCP -->|"uses"| Policy
    Policy -->|"validates"| Mahoraga
    Strategy -->|"rules/prompts"| Mahoraga

    %% Adapter to External
    Alpaca -->|"REST"| AlpacaAPI
    LLM -->|"raw/SDK/Gateway"| OpenAI
    LLM -->|"raw/SDK/Gateway"| AI_SDK
    LLM -->|"raw/SDK/Gateway"| CFGW
    Social -->|"API"| StockTwits
    Social -->|"API"| Reddit
    Social -->|"API"| Twitter
    News -->|"scrape/API"| EDGAR

    %% Click Events
    click Dashboard "https://github.com/ygwyg/mahoraga/tree/main/dashboard/"
    click HTTP "https://github.com/ygwyg/mahoraga/blob/main/src/index.ts"
    click Mahoraga "https://github.com/ygwyg/mahoraga/blob/main/src/durable-objects/mahoraga-harness.ts"
    click Session "https://github.com/ygwyg/mahoraga/blob/main/src/durable-objects/session.ts"
    click Cron "https://github.com/ygwyg/mahoraga/blob/main/src/jobs/cron.ts"
    click Alpaca "https://github.com/ygwyg/mahoraga/blob/main/src/providers/alpaca/client.ts"
    click Alpaca "https://github.com/ygwyg/mahoraga/blob/main/src/providers/alpaca/trading.ts"
    click Alpaca "https://github.com/ygwyg/mahoraga/blob/main/src/providers/alpaca/market-data.ts"
    click Alpaca "https://github.com/ygwyg/mahoraga/blob/main/src/providers/alpaca/options.ts"
    click LLM "https://github.com/ygwyg/mahoraga/blob/main/src/providers/llm/openai.ts"
    click LLM "https://github.com/ygwyg/mahoraga/blob/main/src/providers/llm/ai-sdk.ts"
    click LLM "https://github.com/ygwyg/mahoraga/blob/main/src/providers/llm/cloudflare-gateway.ts"
    click LLM "https://github.com/ygwyg/mahoraga/blob/main/src/providers/llm/factory.ts"
    click LLM "https://github.com/ygwyg/mahoraga/blob/main/src/providers/llm/classifier.ts"
    click Social "https://github.com/ygwyg/mahoraga/blob/main/src/providers/social/stocktwits.ts"
    click News "https://github.com/ygwyg/mahoraga/blob/main/src/providers/news/sec-edgar.ts"
    click News "https://github.com/ygwyg/mahoraga/blob/main/src/providers/scraper.ts"
    click Policy "https://github.com/ygwyg/mahoraga/blob/main/src/policy/engine.ts"
    click Policy "https://github.com/ygwyg/mahoraga/blob/main/src/policy/approval.ts"
    click Policy "https://github.com/ygwyg/mahoraga/blob/main/src/policy/config.ts"
    click Strategy "https://github.com/ygwyg/mahoraga/blob/main/src/strategy/index.ts"
    click Strategy "https://github.com/ygwyg/mahoraga/blob/main/src/strategy/types.ts"
    click Strategy "https://github.com/ygwyg/mahoraga/blob/main/src/strategy/default/index.ts"
    click Strategy "https://github.com/ygwyg/mahoraga/blob/main/src/strategy/default/config.ts"
    click MCP "https://github.com/ygwyg/mahoraga/blob/main/src/mcp/agent.ts"
    click MCP "https://github.com/ygwyg/mahoraga/blob/main/src/mcp/types.ts"
    click D1 "https://github.com/ygwyg/mahoraga/blob/main/src/storage/d1/client.ts"
    click D1 "https://github.com/ygwyg/mahoraga/blob/main/migrations/000*.sql"
    click KV "https://github.com/ygwyg/mahoraga/blob/main/src/storage/kv/client.ts"
    click KV "https://github.com/ygwyg/mahoraga/blob/main/src/storage/kv/keys.ts"
    click R2 "https://github.com/ygwyg/mahoraga/blob/main/src/storage/r2/client.ts"
    click R2 "https://github.com/ygwyg/mahoraga/blob/main/src/storage/r2/paths.ts"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef compute fill:#DFF2D8,stroke:#22863A,color:#22863A;
    classDef storage fill:#FFE8D6,stroke:#D15704,color:#D15704;
    classDef adapter fill:#F0E6FF,stroke:#6F42C1,color:#6F42C1;
    classDef external fill:#F1F1F1,stroke:#6A737D,color:#6A737D;
```
