How ygwyg/mahoraga works
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.