# isahil/doctor-octopus architecture

> Architecture diagram of the GitHub repository isahil/doctor-octopus, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/isahil/doctor-octopus
- Repository: https://github.com/isahil/doctor-octopus

## Overview

##### Project Type and Purpose
- Full-stack web application that orchestrates Playwright test runs, streams live logs in an integrated terminal, and presents HTML test reports via a React-based dashboard.
- Server-side: Python FastAPI app with Socket.IO for real-time communication, Redis (for temporary state/queues), and AWS S3 for report storage.
- Client-side: React SPA with three core UI modules—The Lab (test runner), Terminal (live log stream via xterm.js), and Cards (test-report viewer).

##### Main Components
- Client (React SPA)
– UI Modules: Lab, Xterm terminal, Cards, Navbar, Footer
– Contexts & Hooks: manage Socket.IO, terminal state, lab workflows
- Server (FastAPI + Socket.IO)
– HTTP API endpoints: trigger test runs, fetch report metadata
– WebSocket (Socket.IO) channel: stream live logs from test runner to client
– Playwright Executor: spawns child process to run tests
– Redis: pub/sub or temporary storage for test execution state
– S3 Uploader: pushes final HTML reports and attachments to AWS S3
- External Services
– AWS S3: remote storage of test reports & artifacts
– (Optional) Redis instance: used by server for state management
- CI / E2E Tests
– Playwright folder: end-to-end tests for the app itself (runs in GitHub Actions)

##### Relationships & Data Flows
- User clicks “Run Test” in Lab UI → React issues HTTP POST to FastAPI “/run” endpoint
- FastAPI “executor” module spawns Playwright process → test suite executes
- Playwright stdout/stderr → Server’s “streamer” reads lines → publishes over Socket.IO
- Client Xterm component listens on Socket.IO → renders live logs
- On test completion → Server’s S3 util uploads report files to AWS S3
- Server persists metadata (report ID, S3 URLs) in Redis or in-memory store
- Client Cards module polls or requests HTTP GET “/reports” → displays report cards
- User clicks “View” on a card → React triggers FastAPI to serve local HTML report (via static-file route) or redirects to S3 URL

##### Architectural Patterns & Design Principles
- Separation of Concerns: distinct UI modules (Lab vs. Terminal vs. Cards), distinct server responsibilities (API vs. streaming vs. upload).
- Event-Driven Flow: tests → log events → client via pub/sub (Socket.IO & Redis).
- Micro-service-like decomposition: although monorepo, the client and server are loosely coupled over well-defined HTTP & WebSocket interfaces.
- Scalability: offload test artifacts to AWS S3, use Redis for durable queues if scaled horizontally.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Side
    subgraph "Client (React SPA)"
        direction TB
        LabUI["Lab UI Module"]:::ui
        XtermUI["Xterm Terminal Module"]:::ui
        CardsUI["Cards UI Module"]:::ui
        Navbar["Navbar Component"]:::ui
        Footer["Footer Component"]:::ui
        subgraph "Contexts & Hooks"
            direction TB
            ContextSocket["Socket.IO Context"]:::logic
            ContextLab["Lab Context"]:::logic
            ContextTerm["Terminal Context"]:::logic
            HookIndex["Hooks Index"]:::logic
            HookSocket["Socket.IO Hooks"]:::logic
            HookLab["Lab Hooks"]:::logic
            HookTerm["Terminal Hooks"]:::logic
        end
        RedisClient["Redis Client Utility"]:::util
    end

    %% Server Side
    subgraph "FastAPI Server"
        direction TB
        API["HTTP API Layer"]:::backend
        WS["Socket.IO WebSocket Layer"]:::backend
        Executor["Playwright Executor Module"]:::backend
        Streamer["Log Streamer Module"]:::backend
        RedisUtil["Redis Utility Module"]:::util
        S3Module["AWS S3 Uploader Module"]:::util
        Config["Server Configuration"]:::util
        Startup["Server Startup Script"]:::util
    end

    %% External Services
    subgraph "External Services"
        direction TB
        RedisExt["Redis (optional)"]:::external
        S3["AWS S3 Bucket"]:::external
    end

    %% CI / E2E
    subgraph "CI / E2E Tests"
        direction TB
        GHActions["GitHub Actions"]:::ci
        E2E["Playwright E2E Tests Suite"]:::ci
        RunnerUtils["Test Runner Utilities"]:::ci
        S3Helper["Playwright S3 Helper"]:::ci
    end

    %% Connections
    LabUI -->|"POST /run (HTTP/REST)"| API
    API -->|"spawn()"| Executor
    Executor -->|"stdout/stderr"| Streamer
    Streamer -->|"log stream (Socket.IO)"| WS
    WS -->|"render logs"| XtermUI
    Executor -->|"report files"| S3Module
    S3Module -->|"upload (S3 API)"| S3
    API -->|"save metadata"| RedisUtil
    RedisUtil -->|"pub/sub"| RedisExt
    CardsUI -->|"GET /reports (HTTP/REST)"| API
    CardsUI -->|"view report"| S3
    GHActions -->|"runs tests"| E2E
    E2E -->|"uses"| RunnerUtils
    E2E -->|"uploads artifacts"| S3Helper
    S3Helper -->|"push to"| S3

    %% Click events - Client
    click LabUI "https://github.com/isahil/doctor-octopus/blob/main/client/src/component/lab/lab.jsx"
    click CardsUI "https://github.com/isahil/doctor-octopus/blob/main/client/src/component/card/cards.jsx"
    click XtermUI "https://github.com/isahil/doctor-octopus/blob/main/client/src/component/xterm/xterm.jsx"
    click Navbar "https://github.com/isahil/doctor-octopus/blob/main/client/src/component/navbar/navbar.jsx"
    click Footer "https://github.com/isahil/doctor-octopus/blob/main/client/src/component/footer/footer.jsx"
    click ContextSocket "https://github.com/isahil/doctor-octopus/blob/main/client/src/context/socketio-context.jsx"
    click ContextLab "https://github.com/isahil/doctor-octopus/blob/main/client/src/context/lab-context.jsx"
    click ContextTerm "https://github.com/isahil/doctor-octopus/blob/main/client/src/context/terminal-context.jsx"
    click HookSocket "https://github.com/isahil/doctor-octopus/blob/main/client/src/hooks/socketio-hooks.jsx"
    click HookLab "https://github.com/isahil/doctor-octopus/blob/main/client/src/hooks/lab-hooks.jsx"
    click HookTerm "https://github.com/isahil/doctor-octopus/blob/main/client/src/hooks/terminal-hooks.jsx"
    click RedisClient "https://github.com/isahil/doctor-octopus/blob/main/client/src/util/redis-client.js"
    click ContextSocket "https://github.com/isahil/doctor-octopus/blob/main/client/src/context/index.js"
    click HookIndex "https://github.com/isahil/doctor-octopus/blob/main/client/src/hooks/index.js"

    %% Click events - Server
    click API "https://github.com/isahil/doctor-octopus/blob/main/server/src/fastapi.py"
    click WS "https://github.com/isahil/doctor-octopus/blob/main/server/src/wsocket.py"
    click Executor "https://github.com/isahil/doctor-octopus/blob/main/server/src/util/executor.py"
    click Streamer "https://github.com/isahil/doctor-octopus/blob/main/server/src/util/streamer.py"
    click RedisUtil "https://github.com/isahil/doctor-octopus/blob/main/server/src/util/redis.py"
    click S3Module "https://github.com/isahil/doctor-octopus/blob/main/server/src/util/s3.py"
    click Config "https://github.com/isahil/doctor-octopus/blob/main/server/config.py"
    click Startup "https://github.com/isahil/doctor-octopus/blob/main/server/start.sh"

    %% Click events - CI/E2E
    click E2E "https://github.com/isahil/doctor-octopus/tree/main/playwright/tests"
    click RunnerUtils "https://github.com/isahil/doctor-octopus/blob/main/playwright/utils/runner.js"
    click RunnerUtils "https://github.com/isahil/doctor-octopus/blob/main/playwright/utils/spawn_child_process.js"
    click S3Helper "https://github.com/isahil/doctor-octopus/blob/main/playwright/utils/S3.js"
    click GHActions "https://github.com/isahil/doctor-octopus/blob/main/.github/workflows/dr-ci.yml"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef backend fill:#DFF5E1,stroke:#28a745,color:#28a745
    classDef util fill:#FFF4E5,stroke:#FF8C00,color:#FF8C00
    classDef external fill:#FFF9C4,stroke:#F4B400,color:#F4B400
    classDef logic fill:#E8EAF6,stroke:#5C6BC0,color:#5C6BC0
    classDef ci fill:#F3E5F5,stroke:#9C27B0,color:#9C27B0
```
