# gitaalekhyapaul/skynet-monorepo architecture

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

- Interactive diagram: https://gitdiagram.com/gitaalekhyapaul/skynet-monorepo
- Repository: https://github.com/gitaalekhyapaul/skynet-monorepo

## Overview

This repo is a **TypeScript/Node + React monorepo** for a **cross-chain, semi-autonomous trading bot** (“Skynet”) that:
- Lets users connect **Okto wallets** via a **React frontend** and pool funds.
- Runs an **agentic decision layer** (reAct-style agent, LangGraph/OpenAI) that:
- Creates cross-chain wallets (Polygon + Aptos) using **Okto SDK (custom JWT auth)**,
- Executes **gasless transactions**,
- Reads **Telegram sentiment** (proposals + replies),
- Decides buy/sell actions based on community feedback.

##### File tree analysis (how the repo maps to architecture)
Top-level directories are already the system’s service boundaries:

- `frontend/` — React UI client
- `orchestration/` — API gateway + coordinator + queue manager + realtime updates (Socket.io)
- `agent/` — decision-making worker/service (LangGraph + OpenAI SDK)
- `implementation/` — “business logic & data layer” (DB ops, validation, core operations)

##### README architecture cues (what to reflect verbatim, and what to add)
- **External dependencies**: Okto SDK/Okto wallet, Polygon, Aptos, Telegram, OpenAI
- **Trust boundaries**: browser vs backend network; secrets only in backend; JWT issuance/validation path
- **Sync vs async interactions**: HTTP/WebSocket vs Redis queue jobs
- **Data ownership**: MongoDB as system-of-record for tasks, proposals, trades, user sessions (whatever is applicable)
- **Runtime roles**: Orchestrator as “control-plane”; Agent as “worker”; Implementation as “domain + persistence”

##### Context / C4 Level 1 (System Context)
- User (Browser)
- Okto (Wallet + JWT auth / SDK)
- Polygon + Aptos networks
- Telegram
- OpenAI (or “LLM Provider”)
- Optional: Monitoring/Logging if present (even if implied)

##### Container / C4 Level 2 (Service Topology)
- Frontend → Orchestrator: HTTPS + WebSocket (Socket.io)
- Orchestrator → Redis: enqueue/dequeue job metadata
- Agent → Redis: consume jobs
- Agent → Implementation: HTTP/gRPC (likely HTTP since Express is listed) for domain actions
- Implementation → MongoDB: persistence
- Agent/Implementation → Okto SDK → Chains: wallet creation + tx signing/submission (gasless)
- Agent → Telegram: read/post proposals + parse replies
- Agent → OpenAI: prompt/plan/decide (LangGraph)

- “User submits trading task / strategy update”
- “Agent posts proposal to Telegram → collects replies → decides → executes trade”

##### And label main components (specific to this repo)
Use these as your canonical nodes:

**Client**
- *Frontend (React/TS)*: wallet connect UI, strategy config, status view, task submission

**Control-plane backend**
- *Orchestration (Node/Express/TS)*:
- API Gateway (REST)
- WebSocket gateway (Socket.io) for realtime updates
- Task Manager / System State
- Redis Queue publisher

**Async execution**
- *Redis Queue*: task distribution + buffering + retry semantics (note retry/dlq if implemented)
- *Agent Service (LangGraph + OpenAI SDK)*:
- Task Processor
- ReAct/LangGraph workflow
- Telegram sentiment module
- Execution planner
- Status update publisher back to Orchestrator

**Domain + persistence**
- *Implementation Service (Express/TS)*:
- Business logic
- Data access layer
- Validation, normalization
- *MongoDB*: tasks, users, wallets metadata, proposals, trade records, audit logs (reflect what’s real once confirmed in code)

**External systems**
- Okto SDK / Okto Wallet + JWT auth
- Polygon + Aptos
- Telegram
- OpenAI/LLM

##### Architectural patterns used here (explicitly)
- **API Gateway + Orchestrator** pattern (Frontend has a single backend entrypoint)
- **Queue-based worker** pattern (Redis decouples request submission from execution)
- **Agentic workflow** pattern (LangGraph orchestrates tool calls: Telegram, Okto, DB, LLM)
- **Separation of concerns**: Agent = decisions; Implementation = domain + persistence
- **Event/status streaming** to UI (Socket.io)

##### Decision loop: Proposal → sentiment → decision → execution
It as a feedback loop (Telegram responses feed back into the agent state machine).

##### Async reliability: queue semantics
Job states (Queued/Running/Waiting on Telegram/Completed/Failed) and where they’re stored (MongoDB vs in-memory).

##### Security boundaries
- Browser has no chain execution secrets.
- Backend services hold Okto credentials/JWT handling.
- External calls (Telegram/LLM) are outbound from Agent.

##### “Don’t overthink it”: maximize component separation (what to split out)

**Orchestration**
- REST API
- Socket.io gateway
- Task Manager
- Queue publisher
- (Optional) Auth middleware for Okto session/wallet connect

**Agent**
- LangGraph workflow engine
- Tooling adapters:
- Telegram adapter
- Okto adapter
- Implementation service client
- LLM client
- State machine / memory (where stored?)
- Observability/logging

**Implementation**
- Domain services (trading proposal persistence, trade execution recordkeeping)
- Data access layer (MongoDB collections)
- Validators

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================================================
  %% C4 Level 1 — System Context
  %% =========================================================
  subgraph "C4 L1 — System Context"
    direction TB

    User["User"]:::external
    Browser["Browser (Web Client)"]:::external

    subgraph "Skynet (Cross-chain Semi-autonomous Trading Bot)"
      direction TB
      SkynetSys["Skynet System"]:::system
    end

    Okto["Okto (Wallet + SDK + JWT Auth)"]:::externalCloud
    Polygon["Polygon Network"]:::externalCloud
    Aptos["Aptos Network"]:::externalCloud
    Telegram["Telegram (Proposals + Replies)"]:::externalCloud
    OpenAI["OpenAI / LLM Provider"]:::externalCloud
  end

  User -->|"uses"| Browser
  Browser -->|"interacts"| SkynetSys
  SkynetSys -->|"wallet_ops+gasless_tx"| Okto
  Okto -->|"submit_tx+query_state"| Polygon
  Okto -->|"submit_tx+query_state"| Aptos
  SkynetSys -->|"read_post_sentiment"| Telegram
  SkynetSys -->|"plan_decide"| OpenAI

  %% =========================================================
  %% C4 Level 2 — Container / Service Topology (Main)
  %% =========================================================
  subgraph "C4 L2 — Container / Service Topology"
    direction TB

    %% --- Client lane
    subgraph "Client (Browser Trust Boundary)"
      direction TB
      FE["Frontend (React/TS)\n- Wallet connect UI\n- Strategy config\n- Status/results view"]:::client
    end

    %% --- Control-plane lane
    subgraph "Backend Control-plane (Server Trust Boundary)"
      direction TB

      subgraph "Orchestration Service (Node/Express/TS)"
        direction TB
        ORCH["orchestration/\nOrchestrator Service"]:::service
        ORCH_API["REST API (Gateway)"]:::module
        ORCH_WS["WebSocket Gateway\n(Socket.io)"]:::module
        ORCH_TM["Task Manager / System State"]:::module
        ORCH_QPUB["Redis Queue Publisher"]:::module

        ORCH --> ORCH_API
        ORCH --> ORCH_WS
        ORCH --> ORCH_TM
        ORCH --> ORCH_QPUB
      end

      Redis[("Redis Queue\nJobs/Buffer/Retry")]:::datastore
    end

    %% --- Async/Agent lane
    subgraph "Async Execution Plane"
      direction TB

      subgraph "Agent Service (Node/TS)\nLangGraph + OpenAI SDK"
        direction TB
        AGENT["agent/\nAgent Service"]:::service
        AGENT_PROC["Task Processor"]:::module
        AGENT_LG["ReAct / LangGraph Workflow Engine"]:::module
        AGENT_TG["Telegram Adapter\n(sentiment/proposals)"]:::module
        AGENT_LLM["LLM Client (OpenAI SDK)"]:::module
        AGENT_OKTO["Okto Adapter\n(wallet+gasless tx)"]:::module
        AGENT_IMPLC["Implementation Client\n(HTTP internal)"]:::module
        AGENT_STATE["State Machine / Memory\n(job states)"]:::module
        AGENT_OBS["Logging/Observability"]:::module

        AGENT --> AGENT_PROC
        AGENT_PROC --> AGENT_LG
        AGENT_LG --> AGENT_TG
        AGENT_LG --> AGENT_LLM
        AGENT_LG --> AGENT_OKTO
        AGENT_LG --> AGENT_IMPLC
        AGENT_PROC --> AGENT_STATE
        AGENT --> AGENT_OBS
      end
    end

    %% --- Domain/Data lane
    subgraph "Domain + Data Plane"
      direction TB

      subgraph "Implementation Service (Node/Express/TS)"
        direction TB
        IMPL["implementation/\nImplementation Service"]:::service
        IMPL_DOMAIN["Domain Services\n(trades/proposals/tasks)"]:::module
        IMPL_VALID["Validation/Normalization"]:::module
        IMPL_DAL["Data Access Layer\n(MongoDB driver)"]:::module

        IMPL --> IMPL_DOMAIN
        IMPL --> IMPL_VALID
        IMPL --> IMPL_DAL
      end

      Mongo[("MongoDB\nSystem-of-record:\n- tasks\n- users/sessions\n- wallet metadata\n- proposals\n- trades/audit")]:::datastore
    end

    %% --- External services lane
    subgraph "External Services"
      direction TB
      OKTOX["Okto SDK / Okto Wallet\n(JWT auth, wallet ops)"]:::externalCloud
      CHAINS["Chains\nPolygon + Aptos"]:::externalCloud
      TGX["Telegram API"]:::externalCloud
      LLMX["OpenAI / LLM API"]:::externalCloud
    end
  end

  %% --- Sync control-plane traffic
  FE -->|"HTTPS submit_task/config_strategy"| ORCH_API
  ORCH_WS -->|"WS(Socket.io) stream_status/results"| FE

  %% --- Async queue traffic (dashed)
  ORCH_QPUB -.->|"Redis enqueue_job"| Redis
  Redis -.->|"Redis deliver_job"| AGENT_PROC

  %% --- Progress/events back to control-plane (dashed)
  AGENT_PROC -.->|"progress+completion_events"| ORCH_TM
  ORCH_TM -->|"update_state"| ORCH_WS

  %% --- Agent to domain/data
  AGENT_IMPLC -->|"HTTP internal execute_action/persist_outcome"| IMPL_DOMAIN
  IMPL_DAL -->|"MongoDB read/write"| Mongo

  %% --- External tool calls (outbound from backend)
  AGENT_TG -->|"post_proposal/read_replies"| TGX
  AGENT_LLM -->|"prompt/plan/decide"| LLMX
  AGENT_OKTO -->|"wallet_create+gasless_tx"| OKTOX
  OKTOX -->|"submit_tx+query_state"| CHAINS

  %% --- Decision loop emphasis
  TGX -.->|"replies/sentiment_feedback"| AGENT_STATE
  AGENT_STATE -->|"informs_next_step"| AGENT_LG

  %% =========================================================
  %% C4 Level 3 — Sequence (Core Flow)
  %% =========================================================
  subgraph "C4 L3 — Sequence: Proposal → Sentiment → Decision → Execution"
    direction TB
    S1["1) User configures strategy & submits task (Frontend → Orchestrator)"]:::note
    S2["2) Orchestrator enqueues job to Redis (async)"]:::note
    S3["3) Agent consumes job, runs LangGraph (LLM tool-calls)"]:::note
    S4["4) Agent posts proposal to Telegram & waits for replies (sentiment)"]:::note
    S5["5) Agent decides buy/sell, triggers Okto gasless tx"]:::note
    S6["6) Implementation persists outcome to MongoDB"]:::note
    S7["7) Orchestrator streams status/results back to Frontend (Socket.io)"]:::note

    S1 --> S2 --> S3 --> S4 --> S5 --> S6 --> S7
    S4 -.->|"feedback_loop"| S3
  end

  %% =========================================================
  %% Click Events (from component_mapping)
  %% =========================================================
  click FE "https://github.com/gitaalekhyapaul/skynet-monorepo/tree/main/frontend/"
  click ORCH "https://github.com/gitaalekhyapaul/skynet-monorepo/tree/main/orchestration/"
  click AGENT "https://github.com/gitaalekhyapaul/skynet-monorepo/tree/main/agent/"
  click IMPL "https://github.com/gitaalekhyapaul/skynet-monorepo/tree/main/implementation/"
  click SkynetSys "https://github.com/gitaalekhyapaul/skynet-monorepo/blob/main/README.md"
  click OKTOX "https://github.com/gitaalekhyapaul/skynet-monorepo/blob/main/.gitmodules"

  %% =========================================================
  %% Styles
  %% =========================================================
  classDef system fill:#1f3a5f,stroke:#0b2239,color:#ffffff,stroke-width:1.5px
  classDef client fill:#2b6cb0,stroke:#1a365d,color:#ffffff,stroke-width:1.5px
  classDef service fill:#2f855a,stroke:#1c4532,color:#ffffff,stroke-width:1.5px
  classDef module fill:#68d391,stroke:#1c4532,color:#0b1f14,stroke-width:1px
  classDef datastore fill:#e2e8f0,stroke:#4a5568,color:#1a202c,stroke-width:1.5px
  classDef external fill:#718096,stroke:#2d3748,color:#ffffff,stroke-width:1.5px
  classDef externalCloud fill:#a0aec0,stroke:#2d3748,color:#1a202c,stroke-width:1.5px
  classDef note fill:#fffaf0,stroke:#b7791f,color:#1a202c,stroke-width:1px
```
