# aadityabuilds/recombyne architecture

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

- Interactive diagram: https://gitdiagram.com/aadityabuilds/recombyne
- Repository: https://github.com/aadityabuilds/recombyne

## Overview

##### Project Type and Purpose
- This is a full-stack web application (“Recombyne”) for AI-powered plasmid design.
- Frontend: React + TypeScript + Vite, providing a conversational UI and real-time DNA visualization.
- Backend: Node.js/Express (TypeScript) exposing REST endpoints that orchestrate:
- AI calls (OpenAIService)
- NCBI GenBank queries (GenbankService)
- Python-based DNA optimization (dna_optimization.py via child process)

##### File Structure
- Top‐level:
- public/ – static assets and HTML shell (served by Vite or by Express in prod)
- src/ – application source split into:
– src/components, src/styles, src/App.tsx (React UI layers: split-pane, modals, chat editor)
– src/services/*.ts (client API wrappers for OpenAI, NCBI, plasmid backbone)
– src/server/api/*.ts (Express route handlers for “/dna-optimization” and “/natural-language-to-entrez”)
– src/server/python/ (Python scripts using DNAChisel and helper modules)
- server.ts – entry point for Express server (mounts API routes)
- vite.config.ts, tsconfig.frontend.json, tsconfig.backend.json – separate build targets

##### Extract Architectural Insights from README
- Dual-server setup: Vite dev server (frontend) + Express backend (3001)
- Environment variables configure ports, OpenAI key, NCBI credentials, Python path
- External systems:
- OpenAI API (chat completion, embeddings)
- NCBI E-Utilities (Entrez queries)
- DNAChisel library (sequence optimization)
- @teselagen/ove (embedded in the frontend for sequence visualization)

##### Main Components & Their Interactions
a. Client (Browser)
- React/Vite SPA – renders UI, maintains conversation history in Redux or Context (store.ts)
- Sequence viewer/editor (@teselagen/ove) integrated into EditorPane
- Invokes backend via HTTP (fetch or axios) to /api endpoints
b. API Gateway (Express, server.ts)
- Routes: /api/dna-optimization, /api/natural-language-to-entrez
- Middlewares: error boundary, JSON parsing, CORS
c. Service Layer (backend/services)
- OpenAIService.ts – calls OpenAI REST API
- GenbankService.ts – calls NCBI E-Utilities
- PlasmidBackboneService.ts – loads local catalog of backbones
d. Python Worker
- dna_optimization.py – uses DNAChisel to optimize sequences
- debug_api.py, constraints_reference.py – support modules
- Invoked as a child process from dna-optimization.ts
e. External Systems
- OpenAI cloud endpoints
- NCBI Entrez API

##### Architectural Patterns & Design Principles
- Separation of concerns: UI vs API vs compute (Python)
- Modular services: each external integration lives in its own service class
- Microservice‐style compute offload: heavyweight optimization lives in Python subprocess
- Component-based UI: reusable modals, split panes, error boundaries
- Configuration via environment variables for portability

a. Layout & Components
- Center: Express API Server (server.ts) with two layers: Routes → Service Classes → Worker Orchestrator
- Right: Python Optimization Service (child process)
- Bottom: External APIs (OpenAI, NCBI)
- Data Store (optional): In-memory or Redux store for conversation context
- Browser → Express (HTTP POST /api/…)
- Express → OpenAI / NCBI (HTTPS)
- Express → Python Worker (spawn child, IPC)
- Python Worker → Express (stdout JSON) → Browser (HTTP response)
- UI Components: blue rectangles
- Server Components: green rectangles
- Python Worker: yellow capsule
d. Labels & Annotations
- Environment variables controlling ports, API keys

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "Browser / React SPA"
    direction TB
    SPA["React SPA"]:::frontend
    Chat["ChatInterface"]:::frontend
    SplitP["SplitPane"]:::frontend
    Editor["EditorPane"]:::frontend
    SeqView["SequenceViewer (@teselagen/ove)"]:::frontend
    ErrorBound["ErrorBoundary"]:::frontend
    Modal1["PlasmidSelectorModal"]:::frontend
    Modal2["SequenceOptimizerModal"]:::frontend
    Store["Redux/Context Store"]:::frontend
  end

  subgraph "Express API Server"
    direction TB
    Server["server.ts (Entry Point)"]:::backend
    subgraph "Routes"
      direction TB
      R1["dna-optimization.ts"]:::api
      R2["natural-language-to-entrez.ts"]:::api
    end
    subgraph "Service Layer"
      direction TB
      S1["OpenAIService.ts"]:::service
      S2["GenbankService.ts"]:::service
      S3["PlasmidBackboneService.ts"]:::service
    end
    Orchestrator["Python Worker Orchestrator"]:::backend
  end

  subgraph "Python Optimization Worker"
    direction TB
    PyMain["dna_optimization.py"]:::python
    PyConst["constraints_reference.py"]:::python
    PyDebug["debug_api.py"]:::python
    PyTest["test_optimization.py"]:::python
    PyReq["requirements.txt"]:::python
  end

  subgraph "External Systems"
    direction TB
    OpenAI["OpenAI API"]:::external
    NCBI["NCBI Entrez API"]:::external
    DNAChisel["DNAChisel Library"]:::external
  end

  %% Data Flows
  SPA -->|"HTTP POST /api"| Server
  Chat --> SPA
  SplitP --> SPA
  Editor --> SplitP
  SeqView --> Editor
  ErrorBound --> SPA
  Modal1 --> SplitP
  Modal2 --> SplitP
  Store --> SPA

  Server -->|"mount routes"| R1
  Server -->|"mount routes"| R2
  R1 -->|"uses service"| S1
  R1 -->|"uses service"| S2
  R1 -->|"uses service"| S3
  R2 -->|"uses service"| S2
  R1 -->|"calls"| Orchestrator

  Orchestrator -->|"spawn child (stdio)"| PyMain
  PyMain -->|"imports"| PyConst
  PyMain -->|"imports"| PyDebug
  PyMain -->|"reads deps"| PyReq
  PyMain -->|"stdout JSON"| Orchestrator

  R1 -->|"HTTPS"| OpenAI
  R2 -->|"HTTPS"| NCBI

  Orchestrator -->|"response"| Server
  Server -->|"HTTP Response"| SPA

  %% Click Events
  click SPA "https://github.com/aadityabuilds/recombyne/blob/main/src/index.tsx"
  click Chat "https://github.com/aadityabuilds/recombyne/blob/main/src/components/ChatInterface.tsx"
  click SplitP "https://github.com/aadityabuilds/recombyne/blob/main/src/components/SplitPane.tsx"
  click Editor "https://github.com/aadityabuilds/recombyne/blob/main/src/components/EditorPane.tsx"
  click ErrorBound "https://github.com/aadityabuilds/recombyne/blob/main/src/components/ErrorBoundary.tsx"
  click Modal1 "https://github.com/aadityabuilds/recombyne/blob/main/src/components/PlasmidSelectorModal.tsx"
  click Modal2 "https://github.com/aadityabuilds/recombyne/blob/main/src/components/SequenceOptimizerModal.tsx"
  click Store "https://github.com/aadityabuilds/recombyne/blob/main/src/store.ts"
  click Server "https://github.com/aadityabuilds/recombyne/blob/main/server.ts"
  click R1 "https://github.com/aadityabuilds/recombyne/blob/main/src/server/api/dna-optimization.ts"
  click R2 "https://github.com/aadityabuilds/recombyne/blob/main/src/server/api/natural-language-to-entrez.ts"
  click PyMain "https://github.com/aadityabuilds/recombyne/blob/main/src/server/python/dna_optimization.py"
  click PyConst "https://github.com/aadityabuilds/recombyne/blob/main/src/server/python/constraints_reference.py"
  click PyDebug "https://github.com/aadityabuilds/recombyne/blob/main/src/server/python/debug_api.py"
  click PyTest "https://github.com/aadityabuilds/recombyne/blob/main/src/server/python/test_optimization.py"
  click PyReq "https://github.com/aadityabuilds/recombyne/blob/main/src/server/python/requirements.txt"

  %% Styles
  classDef frontend fill:#AEDFF7,stroke:#333,stroke-width:1px;
  classDef backend fill:#C8E6C9,stroke:#333,stroke-width:1px;
  classDef service fill:#A5D6A7,stroke:#333,stroke-width:1px;
  classDef api fill:#81C784,stroke:#333,stroke-width:1px;
  classDef python fill:#FFF59D,stroke:#333,stroke-width:1px;
  classDef external fill:#E0E0E0,stroke:#333,stroke-width:1px;
```
