How isahil/doctor-octopus works
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.