# se7en69/proteinscape architecture

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

- Interactive diagram: https://gitdiagram.com/se7en69/proteinscape
- Repository: https://github.com/se7en69/proteinscape

## Overview

##### Project type and purpose
- ProteinScape is a lightweight, web‐based full-stack application built with Streamlit.

##### File structure
- Top-level files:
– app.py: contains the single Streamlit application (both front-end and glue code for backend calls).
– requirements.txt: lists all dependencies (Streamlit, py3Dmol, Matplotlib, Seaborn, Pandas, Requests, NumPy).
– README.md / LICENSE: documentation and license.
- No separate “frontend” or “backend” directories: the architecture is a monolithic Streamlit service that integrates UI, data handling, plotting, and external API calls.

##### README for additional insights
- Frontend: Streamlit app.py
- Backend integration: Python requests to ESMFold API
- Visualization: py3Dmol for 3D, Matplotlib/Seaborn for 2D plots
- Data handling: Pandas, built-in collections
- File I/O: FASTA upload, PDB download

A. Client (Web Browser)
B. Streamlit Service (app.py)
1. UI layer (form inputs, buttons)
2. Controller logic (handles button clicks, file uploads)
3. API client (Requests → ESMFold API)
4. Data processor (Pandas, Collections)
5. Plot generator (Matplotlib, Seaborn)
6. 3D renderer (py3Dmol)
C. External Service
– ESMFold API (remote protein structure predictor)
D. File System / User Assets
– Uploaded FASTA files
– Downloadable PDB files

– Browser → Streamlit Service (HTTP/WebSocket calls handled by Streamlit)
– Streamlit Service → ESMFold API (HTTPS REST request)
– ESMFold API → Streamlit Service (PDB response)
– Streamlit Service → Browser (3D viewer, plots, downloads)

##### Architectural patterns and design principles
- Single-page interactive web application
- Monolithic service with clearly separated internal modules (UI vs. API vs. data vs. viz)
- External API integration for compute-intensive work (protein folding)
- Client-server separation: all business logic lives on the server (Streamlit), browser only renders results

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User and File System
    subgraph "User"
        direction TB
        Browser["User Browser"]:::frontend
    end

    subgraph "File System / User Assets"
        direction TB
        FASTAUpload[(FASTA File Upload)]:::fileio
        PDBDownload[(PDB File Download)]:::fileio
    end

    %% Streamlit Service Monolith
    subgraph "Streamlit Service"
        direction TB
        UI["UI (Forms & Buttons)"]:::frontend
        Controller["Controller & Business Logic"]:::internal
        APIClient["API Client (Requests → ESMFold)"]:::internal
        DataProcessor["Data Processor (Pandas, Collections)"]:::internal
        PlotGenerator["Plot Generator (Matplotlib, Seaborn)"]:::internal
        Renderer3D["3D Renderer (py3Dmol)"]:::internal
    end

    %% External API
    External["ESMFold API"]:::external

    %% Project Files
    subgraph "Project Files"
        direction TB
        Docs["README.md"]:::fileio
        Deps["requirements.txt"]:::fileio
        License["LICENSE"]:::fileio
    end

    %% Connections
    Browser --> UI
    Browser --> FASTAUpload
    FASTAUpload --> UI
    UI --> Controller
    Controller --> APIClient
    APIClient --> External
    External --> APIClient
    Controller --> DataProcessor
    Controller --> PlotGenerator
    Controller --> Renderer3D
    DataProcessor --> PlotGenerator
    PlotGenerator --> Browser
    Renderer3D --> Browser
    Controller --> PDBDownload
    PDBDownload --> Browser

    %% Click Events
    click UI "https://github.com/se7en69/proteinscape/blob/main/app.py"
    click Controller "https://github.com/se7en69/proteinscape/blob/main/app.py"
    click APIClient "https://github.com/se7en69/proteinscape/blob/main/app.py"
    click DataProcessor "https://github.com/se7en69/proteinscape/blob/main/app.py"
    click PlotGenerator "https://github.com/se7en69/proteinscape/blob/main/app.py"
    click Renderer3D "https://github.com/se7en69/proteinscape/blob/main/app.py"
    click Docs "https://github.com/se7en69/proteinscape/blob/main/README.md"
    click Deps "https://github.com/se7en69/proteinscape/blob/main/requirements.txt"
    click License "https://github.com/se7en69/proteinscape/tree/main/LICENSE"

    %% Styles
    classDef frontend fill:#D6E5FF,stroke:#0366D6,stroke-width:2px;
    classDef internal fill:#E6F4EA,stroke:#34A853,stroke-width:2px;
    classDef external fill:#FFE8D6,stroke:#EA580C,stroke-width:2px;
    classDef fileio fill:#F1F3F4,stroke:#5F5F5F,stroke-width:2px;
```
