# facundodlf/investment-ceo-ai architecture

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

- Interactive diagram: https://gitdiagram.com/facundodlf/investment-ceo-ai
- Repository: https://github.com/facundodlf/investment-ceo-ai

## Overview

Investment CEO AI is an autonomous, multi-agent trading system. Its documented operating loop gathers venue positions and market analysis, then gives the CEO agent account context and a mandate; the CEO validates intent and dispatches trading or specialist commands. Quant, research, Scrappy, and Octavio provide distinct analysis or execution capabilities, while venue adapters normalize broker operations and Prisma-backed services retain mission and performance state. The README also documents multiple brokers, options, hard-stop controls, and LLM fallback. Some specialist and tool internals were not sampled, so those links are limited to documented or indexed relationships.

Main entry points: [`src/features/agent/services/agent.service.ts`](https://github.com/facundodlf/investment-ceo-ai/blob/main/src/features/agent/services/agent.service.ts) (CEO agent), [`src/features/venues/venue.service.ts`](https://github.com/facundodlf/investment-ceo-ai/blob/main/src/features/venues/venue.service.ts) (Venue registry), [`src/processes/daemon/ceo.loop.ts`](https://github.com/facundodlf/investment-ceo-ai/blob/main/src/processes/daemon/ceo.loop.ts) (CEO loop), [`src/features/agent/sub-agents/octavio.agent.ts`](https://github.com/facundodlf/investment-ceo-ai/blob/main/src/features/agent/sub-agents/octavio.agent.ts) (Octavio agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Trading runtime"]
  node_ceo_loop["CEO loop<br/>[ceo.loop.ts]"]
  node_iol_loop["IOL loop<br/>[iol.loop.ts]"]
end

subgraph group_agents["Agents and analysis"]
  node_agent["CEO agent<br/>[agent.service.ts]"]
  node_mandate["CEO mandate<br/>[ceo.mandate.ts]"]
  node_quant["Quant agent<br/>[quant.agent.ts]"]
  node_research["Research agent<br/>[research.agent.ts]"]
  node_scanner["Market scanner"]
  node_scrappy["Scrappy agent<br/>[scrappy.agent.ts]"]
  node_octavio["Octavio agent<br/>[octavio.agent.ts]"]
  node_research_tools["Web research tools"]
  node_account_state["Account context<br/>[getAccountState.ts]"]
end

subgraph group_execution["Trading execution"]
  node_trade_tools["Trade tools"]
  node_validation["Intent validation"]
  node_risk["Risk sizing<br/>[risk.engine.ts]"]
  node_venue_service["Venue registry<br/>[venue.service.ts]"]
  node_alpaca["Alpaca adapter<br/>[alpaca.adapter.ts]"]
  node_bybit["Bybit adapter<br/>[bybit.adapter.ts]"]
  node_iol["IOL adapter<br/>[iol.adapter.ts]"]
end

subgraph group_platform["State and providers"]
  node_state["Agent state<br/>[state.service.ts]"]
  node_missions["Mission state<br/>[mission.service.ts]"]
  node_database[("PostgreSQL<br/>[prisma.ts]")]
  node_llm_router["LLM fallback<br/>[groq.ts]"]
end

node_operator(("Operator"))
node_venue_api{{"Broker APIs"}}
node_llm{{"LLM providers"}}

node_operator -.->|"starts cycle"| node_ceo_loop
node_operator -.->|"starts IOL"| node_iol_loop
node_ceo_loop -->|"requests analysis"| node_quant
node_ceo_loop -->|"submits context"| node_agent
node_iol_loop -->|"runs CEO"| node_agent
node_ceo_loop -->|"reads positions"| node_venue_service
node_ceo_loop -->|"executes orders"| node_venue_service
node_agent -->|"requests completion"| node_llm_router
node_agent -->|"dispatches account tool"| node_account_state
node_agent -->|"dispatches trade tool"| node_trade_tools
node_agent -->|"dispatches validation"| node_validation
node_agent -.->|"delegates analysis"| node_research
node_agent -.->|"commands specialist"| node_scrappy
node_agent -.->|"commands specialist"| node_octavio
node_research -->|"requests completion"| node_llm_router
node_research -->|"executes searches"| node_research_tools
node_agent -->|"uses mandate"| node_mandate
node_validation -.->|"checks risk"| node_risk
node_trade_tools -.->|"routes orders"| node_venue_service
node_quant -.->|"queries venues"| node_venue_service
node_account_state -->|"reads account data"| node_venue_service
node_account_state -->|"reads state"| node_state
node_missions -->|"reads and writes"| node_database
node_state -.->|"provides configuration"| node_agent
node_venue_service -->|"dispatches venue calls"| node_alpaca
node_venue_service -->|"dispatches venue calls"| node_bybit
node_venue_service -->|"dispatches venue calls"| node_iol
node_alpaca -.->|"calls broker"| node_venue_api
node_bybit -.->|"calls broker"| node_venue_api
node_iol -.->|"calls broker"| node_venue_api
node_llm_router -.->|"calls providers"| node_llm
node_octavio -->|"uses options venues"| node_venue_service
node_octavio -->|"updates mission state"| node_missions
node_octavio -->|"persists state"| node_database
node_ceo_loop -->|"requests research"| node_research
node_ceo_loop -->|"uses market scan"| node_scanner

click node_ceo_loop "https://github.com/facundodlf/investment-ceo-ai/blob/main/src/processes/daemon/ceo.loop.ts"
click node_iol_loop "https://github.com/facundodlf/investment-ceo-ai/blob/main/src/processes/daemon/iol.loop.ts"
click node_agent "https://github.com/facundodlf/investment-ceo-ai/blob/main/src/features/agent/services/agent.service.ts"
click node_mandate "https://github.com/facundodlf/investment-ceo-ai/blob/main/src/features/agent/config/ceo.mandate.ts"
click node_quant "https://github.com/facundodlf/investment-ceo-ai/blob/main/src/features/agent/sub-agents/quant.agent.ts"
click node_research "https://github.com/facundodlf/investment-ceo-ai/blob/main/src/features/agent/sub-agents/research.agent.ts"
click node_scanner "https://github.com/facundodlf/investment-ceo-ai/blob/main/src/features/agent/sub-agents/market-scanner.agent.ts"
click node_scrappy "https://github.com/facundodlf/investment-ceo-ai/blob/main/src/features/agent/sub-agents/scrappy.agent.ts"
click node_octavio "https://github.com/facundodlf/investment-ceo-ai/blob/main/src/features/agent/sub-agents/octavio.agent.ts"
click node_research_tools "https://github.com/facundodlf/investment-ceo-ai/blob/main/src/features/agent/tools/serper-search.tool.ts"
click node_trade_tools "https://github.com/facundodlf/investment-ceo-ai/blob/main/src/features/agent/tools/execute-trade.tool.ts"
click node_validation "https://github.com/facundodlf/investment-ceo-ai/blob/main/src/features/agent/tools/validate-trade-intent.tool.ts"
click node_risk "https://github.com/facundodlf/investment-ceo-ai/blob/main/src/features/risk/risk.engine.ts"
click node_venue_service "https://github.com/facundodlf/investment-ceo-ai/blob/main/src/features/venues/venue.service.ts"
click node_alpaca "https://github.com/facundodlf/investment-ceo-ai/blob/main/src/features/venues/alpaca.adapter.ts"
click node_bybit "https://github.com/facundodlf/investment-ceo-ai/blob/main/src/features/venues/bybit.adapter.ts"
click node_iol "https://github.com/facundodlf/investment-ceo-ai/blob/main/src/features/venues/iol.adapter.ts"
click node_state "https://github.com/facundodlf/investment-ceo-ai/blob/main/src/features/agent/services/state.service.ts"
click node_missions "https://github.com/facundodlf/investment-ceo-ai/blob/main/src/features/agent/services/mission.service.ts"
click node_database "https://github.com/facundodlf/investment-ceo-ai/blob/main/src/shared/lib/prisma.ts"
click node_llm_router "https://github.com/facundodlf/investment-ceo-ai/blob/main/src/shared/lib/groq.ts"
click node_account_state "https://github.com/facundodlf/investment-ceo-ai/blob/main/src/features/agent/skills/getAccountState.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_ceo_loop,node_iol_loop toneBlue
class node_agent,node_mandate,node_quant,node_research,node_scanner,node_scrappy,node_octavio,node_research_tools,node_account_state toneAmber
class node_trade_tools,node_validation,node_risk,node_venue_service,node_alpaca,node_bybit,node_iol,node_venue_api toneMint
class node_state,node_missions,node_database,node_llm_router toneRose
class node_operator,node_llm toneIndigo
```

## Components

### Trading runtime

- [CEO loop](https://github.com/facundodlf/investment-ceo-ai/blob/main/src/processes/daemon/ceo.loop.ts): `src/processes/daemon/ceo.loop.ts`
- [IOL loop](https://github.com/facundodlf/investment-ceo-ai/blob/main/src/processes/daemon/iol.loop.ts): `src/processes/daemon/iol.loop.ts`

### Agents and analysis

- [CEO agent](https://github.com/facundodlf/investment-ceo-ai/blob/main/src/features/agent/services/agent.service.ts): `src/features/agent/services/agent.service.ts`
- [CEO mandate](https://github.com/facundodlf/investment-ceo-ai/blob/main/src/features/agent/config/ceo.mandate.ts): `src/features/agent/config/ceo.mandate.ts`
- [Quant agent](https://github.com/facundodlf/investment-ceo-ai/blob/main/src/features/agent/sub-agents/quant.agent.ts): `src/features/agent/sub-agents/quant.agent.ts`
- [Research agent](https://github.com/facundodlf/investment-ceo-ai/blob/main/src/features/agent/sub-agents/research.agent.ts): `src/features/agent/sub-agents/research.agent.ts`
- [Market scanner](https://github.com/facundodlf/investment-ceo-ai/blob/main/src/features/agent/sub-agents/market-scanner.agent.ts): `src/features/agent/sub-agents/market-scanner.agent.ts`
- [Scrappy agent](https://github.com/facundodlf/investment-ceo-ai/blob/main/src/features/agent/sub-agents/scrappy.agent.ts): `src/features/agent/sub-agents/scrappy.agent.ts`
- [Octavio agent](https://github.com/facundodlf/investment-ceo-ai/blob/main/src/features/agent/sub-agents/octavio.agent.ts): `src/features/agent/sub-agents/octavio.agent.ts`
- [Web research tools](https://github.com/facundodlf/investment-ceo-ai/blob/main/src/features/agent/tools/serper-search.tool.ts): `src/features/agent/tools/serper-search.tool.ts`
- [Account context](https://github.com/facundodlf/investment-ceo-ai/blob/main/src/features/agent/skills/getAccountState.ts): `src/features/agent/skills/getAccountState.ts`

### Trading execution

- [Trade tools](https://github.com/facundodlf/investment-ceo-ai/blob/main/src/features/agent/tools/execute-trade.tool.ts): `src/features/agent/tools/execute-trade.tool.ts`
- [Intent validation](https://github.com/facundodlf/investment-ceo-ai/blob/main/src/features/agent/tools/validate-trade-intent.tool.ts): `src/features/agent/tools/validate-trade-intent.tool.ts`
- [Risk sizing](https://github.com/facundodlf/investment-ceo-ai/blob/main/src/features/risk/risk.engine.ts): `src/features/risk/risk.engine.ts`
- [Venue registry](https://github.com/facundodlf/investment-ceo-ai/blob/main/src/features/venues/venue.service.ts): `src/features/venues/venue.service.ts`
- [Alpaca adapter](https://github.com/facundodlf/investment-ceo-ai/blob/main/src/features/venues/alpaca.adapter.ts): `src/features/venues/alpaca.adapter.ts`
- [Bybit adapter](https://github.com/facundodlf/investment-ceo-ai/blob/main/src/features/venues/bybit.adapter.ts): `src/features/venues/bybit.adapter.ts`
- [IOL adapter](https://github.com/facundodlf/investment-ceo-ai/blob/main/src/features/venues/iol.adapter.ts): `src/features/venues/iol.adapter.ts`

### State and providers

- [Agent state](https://github.com/facundodlf/investment-ceo-ai/blob/main/src/features/agent/services/state.service.ts): `src/features/agent/services/state.service.ts`
- [Mission state](https://github.com/facundodlf/investment-ceo-ai/blob/main/src/features/agent/services/mission.service.ts): `src/features/agent/services/mission.service.ts`
- [PostgreSQL](https://github.com/facundodlf/investment-ceo-ai/blob/main/src/shared/lib/prisma.ts): `src/shared/lib/prisma.ts`
- [LLM fallback](https://github.com/facundodlf/investment-ceo-ai/blob/main/src/shared/lib/groq.ts): `src/shared/lib/groq.ts`

### Other components

- **Operator**
- **Broker APIs**
- **LLM providers**

## Connections

- Operator → CEO loop: starts cycle (evidence: `README.md`)
- Operator → IOL loop: starts IOL (evidence: `README.md`)
- CEO loop → Quant agent: requests analysis (evidence: `src/processes/daemon/ceo.loop.ts`)
- CEO loop → CEO agent: submits context (evidence: `src/processes/daemon/ceo.loop.ts`)
- IOL loop → CEO agent: runs CEO (evidence: `src/processes/daemon/iol.loop.ts`)
- CEO loop → Venue registry: reads positions (evidence: `src/processes/daemon/ceo.loop.ts`)
- CEO loop → Venue registry: executes orders (evidence: `src/processes/daemon/ceo.loop.ts`)
- CEO agent → LLM fallback: requests completion (evidence: `src/features/agent/services/agent.service.ts`)
- CEO agent → Account context: dispatches account tool (evidence: `src/features/agent/services/agent.service.ts`)
- CEO agent → Trade tools: dispatches trade tool (evidence: `src/features/agent/services/agent.service.ts`)
- CEO agent → Intent validation: dispatches validation (evidence: `src/features/agent/services/agent.service.ts`)
- CEO agent → Research agent: delegates analysis
- CEO agent → Scrappy agent: commands specialist
- CEO agent → Octavio agent: commands specialist
- Research agent → LLM fallback: requests completion (evidence: `src/features/agent/sub-agents/research.agent.ts`)
- Research agent → Web research tools: executes searches (evidence: `src/features/agent/sub-agents/research.agent.ts`)
- CEO agent → CEO mandate: uses mandate (evidence: `src/features/agent/services/agent.service.ts`)
- Intent validation → Risk sizing: checks risk
- Trade tools → Venue registry: routes orders
- Quant agent → Venue registry: queries venues (evidence: `src/features/agent/sub-agents/quant.agent.ts`)
- Account context → Venue registry: reads account data (evidence: `src/features/agent/skills/getAccountState.ts`)
- Account context → Agent state: reads state (evidence: `src/features/agent/skills/getAccountState.ts`)
- Mission state → PostgreSQL: reads and writes (evidence: `src/features/agent/services/mission.service.ts`)
- Agent state → CEO agent: provides configuration
- Venue registry → Alpaca adapter: dispatches venue calls (evidence: `src/features/venues/venue.service.ts`)
- Venue registry → Bybit adapter: dispatches venue calls (evidence: `src/features/venues/venue.service.ts`)
- Venue registry → IOL adapter: dispatches venue calls (evidence: `src/features/venues/venue.service.ts`)
- Alpaca adapter → Broker APIs: calls broker
- Bybit adapter → Broker APIs: calls broker
- IOL adapter → Broker APIs: calls broker
- LLM fallback → LLM providers: calls providers (evidence: `src/shared/lib/groq.ts`)
- Octavio agent → Venue registry: uses options venues (evidence: `src/features/agent/sub-agents/octavio.agent.ts`)
- Octavio agent → Mission state: updates mission state (evidence: `src/features/agent/sub-agents/octavio.agent.ts`)
- Octavio agent → PostgreSQL: persists state (evidence: `src/features/agent/sub-agents/octavio.agent.ts`)
- CEO loop → Research agent: requests research (evidence: `src/processes/daemon/ceo.loop.ts`)
- CEO loop → Market scanner: uses market scan (evidence: `src/processes/daemon/ceo.loop.ts`)