# frosty-mug/umbrella architecture

> Architecture diagram of the GitHub repository frosty-mug/umbrella, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/frosty-mug/umbrella
- Repository: https://github.com/frosty-mug/umbrella

## Overview

Umbrella OS combines a windowed desktop for genomic research with a FastAPI compute backend. Users open scientific apps, select or upload samples, inspect sequence quality and resistance findings, explore cohort analytics or simulations, and use research and reporting tools; backend routes expose authentication, persistence, analysis, and AI orchestration. The README documents additional app capabilities not present in sampled source, which are represented at their app-directory paths. Some subsystem links rely on README claims or the source index rather than inspected implementations.

Main entry points: [`apps/desktop/app/page.tsx`](https://github.com/frosty-mug/umbrella/blob/main/apps/desktop/app/page.tsx) (Desktop Shell), [`services/api/main.py`](https://github.com/frosty-mug/umbrella/blob/main/services/api/main.py) (FastAPI Service), [`ml/training/train_baseline.py`](https://github.com/frosty-mug/umbrella/blob/main/ml/training/train_baseline.py) (Model Training), [`apps/desktop/lib/store.ts`](https://github.com/frosty-mug/umbrella/blob/main/apps/desktop/lib/store.ts) (Window and Sample State)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop OS"]
  node_desktop["Desktop Shell<br/>[page.tsx]"]
  node_store["Window and Sample State<br/>[store.ts]"]
  node_windowing["Windowing and Launcher"]
  node_clearance["Clearance Login"]
end

subgraph group_research["Research Apps"]
  node_genomics["Genome Analysis Apps"]
  node_competitor["Genome Competitor"]
  node_sequence["Sequence QC<br/>[SequenceQCApp.tsx]"]
  node_samplevault["Sample Vault<br/>[SampleVaultApp.tsx]"]
  node_analysis["Cohort Analytics"]
  node_stress["Stress Simulators<br/>[StressLabApp.tsx]"]
  node_science_lab["Science Lab<br/>[ScienceLabApp.tsx]"]
  node_researchdesk["Research Desk"]
  node_terminal["Bio-Terminal<br/>[BioTerminalApp.tsx]"]
  node_reporting["Reports and Export"]
  node_vella_ui["Vella Assistant<br/>[VellaApp.tsx]"]
end

subgraph group_api["API Services"]
  node_api["FastAPI Service<br/>[main.py]"]
  node_auth["Authentication and Roles<br/>[auth_router.py]"]
  node_persistence[("Database and Domain Records<br/>[database.py]")]
  node_amr_api["AMR Training API"]
  node_bio_api["Competitor and Stress APIs"]
  node_vella["Vella Orchestrator<br/>[orchestrator.py]"]
end

subgraph group_science["Bioinformatics"]
  node_sequence_engine["FASTA Parsing and QC<br/>[fasta_parser.py]"]
  node_amrfinder["AMR Annotation<br/>[amrfinder.py]"]
end

subgraph group_ml["AMR Modeling"]
  node_features["AMR Feature Extraction<br/>[extractor.py]"]
  node_training["Model Training<br/>[train_baseline.py]"]
  node_registry[("Model Registry<br/>[model_store.py]")]
end

node_researcher(("Researcher"))
node_providers["AI Model Providers"]

node_researcher -->|"opens desktop"| node_desktop
node_desktop -->|"renders windows"| node_windowing
node_desktop -->|"reads window state"| node_store
node_desktop -->|"renders clearance"| node_clearance
node_store -->|"tracks window state"| node_windowing
node_desktop -->|"dispatches app"| node_genomics
node_desktop -->|"dispatches app"| node_competitor
node_desktop -.->|"dispatches app"| node_sequence
node_desktop -.->|"dispatches app"| node_samplevault
node_desktop -->|"dispatches app"| node_analysis
node_desktop -->|"dispatches app"| node_stress
node_desktop -->|"dispatches app"| node_science_lab
node_desktop -->|"dispatches app"| node_researchdesk
node_desktop -->|"dispatches app"| node_terminal
node_desktop -->|"dispatches app"| node_reporting
node_desktop -->|"dispatches app"| node_vella_ui
node_researcher -->|"selects sample"| node_samplevault
node_researcher -->|"uploads FASTA"| node_sequence
node_api -->|"runs sequence QC"| node_sequence_engine
node_api -->|"persists records"| node_persistence
node_api -->|"mounts routes"| node_auth
node_api -->|"mounts routes"| node_amr_api
node_api -->|"mounts routes"| node_bio_api
node_api -->|"dispatches requests"| node_vella
node_sequence_engine -.->|"provides sequence input"| node_amrfinder
node_amrfinder -->|"provides annotations"| node_features
node_training -->|"extracts features"| node_features
node_amr_api -->|"checks role"| node_auth
node_vella -->|"requests AI response"| node_providers
node_researcher -->|"explores cohorts"| node_analysis
node_researcher -->|"runs simulations"| node_stress
node_researcher -->|"records investigation"| node_researchdesk
node_researcher -->|"exports dossier"| node_reporting
node_training -.->|"registers models"| node_registry

click node_desktop "https://github.com/frosty-mug/umbrella/blob/main/apps/desktop/app/page.tsx"
click node_store "https://github.com/frosty-mug/umbrella/blob/main/apps/desktop/lib/store.ts"
click node_windowing "https://github.com/frosty-mug/umbrella/tree/main/apps/desktop/components/desktop"
click node_clearance "https://github.com/frosty-mug/umbrella/blob/main/apps/desktop/components/BiotechLoginModal.tsx"
click node_genomics "https://github.com/frosty-mug/umbrella/blob/main/apps/desktop/apps/GenomeAnalyzerApp.tsx"
click node_competitor "https://github.com/frosty-mug/umbrella/blob/main/apps/desktop/apps/GenomeCompetitorApp.tsx"
click node_sequence "https://github.com/frosty-mug/umbrella/blob/main/apps/desktop/apps/SequenceQCApp.tsx"
click node_samplevault "https://github.com/frosty-mug/umbrella/blob/main/apps/desktop/apps/SampleVaultApp.tsx"
click node_analysis "https://github.com/frosty-mug/umbrella/blob/main/apps/desktop/apps/AnalysisStudioApp.tsx"
click node_stress "https://github.com/frosty-mug/umbrella/blob/main/apps/desktop/apps/StressLabApp.tsx"
click node_science_lab "https://github.com/frosty-mug/umbrella/blob/main/apps/desktop/apps/ScienceLabApp.tsx"
click node_researchdesk "https://github.com/frosty-mug/umbrella/blob/main/apps/desktop/apps/ResearchDeskApp.tsx"
click node_terminal "https://github.com/frosty-mug/umbrella/blob/main/apps/desktop/apps/BioTerminalApp.tsx"
click node_reporting "https://github.com/frosty-mug/umbrella/blob/main/apps/desktop/apps/ReportStudioApp.tsx"
click node_vella_ui "https://github.com/frosty-mug/umbrella/blob/main/apps/desktop/apps/VellaApp.tsx"
click node_api "https://github.com/frosty-mug/umbrella/blob/main/services/api/main.py"
click node_auth "https://github.com/frosty-mug/umbrella/blob/main/services/api/auth_router.py"
click node_persistence "https://github.com/frosty-mug/umbrella/blob/main/services/api/database.py"
click node_amr_api "https://github.com/frosty-mug/umbrella/blob/main/services/api/amr_pipeline_router.py"
click node_bio_api "https://github.com/frosty-mug/umbrella/tree/main/services/api"
click node_vella "https://github.com/frosty-mug/umbrella/blob/main/services/vella/orchestrator.py"
click node_sequence_engine "https://github.com/frosty-mug/umbrella/blob/main/core/bio/fasta_parser.py"
click node_amrfinder "https://github.com/frosty-mug/umbrella/blob/main/core/bio/amrfinder.py"
click node_features "https://github.com/frosty-mug/umbrella/blob/main/ml/features/extractor.py"
click node_training "https://github.com/frosty-mug/umbrella/blob/main/ml/training/train_baseline.py"
click node_registry "https://github.com/frosty-mug/umbrella/blob/main/ml/registry/model_store.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_desktop,node_store,node_windowing,node_clearance toneBlue
class node_genomics,node_competitor,node_sequence,node_samplevault,node_analysis,node_stress,node_science_lab,node_researchdesk,node_terminal,node_reporting,node_vella_ui toneAmber
class node_api,node_auth,node_persistence,node_amr_api,node_bio_api,node_vella toneMint
class node_sequence_engine,node_amrfinder toneRose
class node_features,node_training,node_registry,node_researcher,node_providers toneIndigo
```

## Components

### Desktop OS

- [Desktop Shell](https://github.com/frosty-mug/umbrella/blob/main/apps/desktop/app/page.tsx): `apps/desktop/app/page.tsx`
- [Window and Sample State](https://github.com/frosty-mug/umbrella/blob/main/apps/desktop/lib/store.ts): `apps/desktop/lib/store.ts`
- [Windowing and Launcher](https://github.com/frosty-mug/umbrella/tree/main/apps/desktop/components/desktop): `apps/desktop/components/desktop`
- [Clearance Login](https://github.com/frosty-mug/umbrella/blob/main/apps/desktop/components/BiotechLoginModal.tsx): `apps/desktop/components/BiotechLoginModal.tsx`

### Research Apps

- [Genome Analysis Apps](https://github.com/frosty-mug/umbrella/blob/main/apps/desktop/apps/GenomeAnalyzerApp.tsx): `apps/desktop/apps/GenomeAnalyzerApp.tsx`
- [Genome Competitor](https://github.com/frosty-mug/umbrella/blob/main/apps/desktop/apps/GenomeCompetitorApp.tsx): `apps/desktop/apps/GenomeCompetitorApp.tsx`
- [Sequence QC](https://github.com/frosty-mug/umbrella/blob/main/apps/desktop/apps/SequenceQCApp.tsx): `apps/desktop/apps/SequenceQCApp.tsx`
- [Sample Vault](https://github.com/frosty-mug/umbrella/blob/main/apps/desktop/apps/SampleVaultApp.tsx): `apps/desktop/apps/SampleVaultApp.tsx`
- [Cohort Analytics](https://github.com/frosty-mug/umbrella/blob/main/apps/desktop/apps/AnalysisStudioApp.tsx): `apps/desktop/apps/AnalysisStudioApp.tsx`
- [Stress Simulators](https://github.com/frosty-mug/umbrella/blob/main/apps/desktop/apps/StressLabApp.tsx): `apps/desktop/apps/StressLabApp.tsx`
- [Science Lab](https://github.com/frosty-mug/umbrella/blob/main/apps/desktop/apps/ScienceLabApp.tsx): `apps/desktop/apps/ScienceLabApp.tsx`
- [Research Desk](https://github.com/frosty-mug/umbrella/blob/main/apps/desktop/apps/ResearchDeskApp.tsx): `apps/desktop/apps/ResearchDeskApp.tsx`
- [Bio-Terminal](https://github.com/frosty-mug/umbrella/blob/main/apps/desktop/apps/BioTerminalApp.tsx): `apps/desktop/apps/BioTerminalApp.tsx`
- [Reports and Export](https://github.com/frosty-mug/umbrella/blob/main/apps/desktop/apps/ReportStudioApp.tsx): `apps/desktop/apps/ReportStudioApp.tsx`
- [Vella Assistant](https://github.com/frosty-mug/umbrella/blob/main/apps/desktop/apps/VellaApp.tsx): `apps/desktop/apps/VellaApp.tsx`

### API Services

- [FastAPI Service](https://github.com/frosty-mug/umbrella/blob/main/services/api/main.py): `services/api/main.py`
- [Authentication and Roles](https://github.com/frosty-mug/umbrella/blob/main/services/api/auth_router.py): `services/api/auth_router.py`
- [Database and Domain Records](https://github.com/frosty-mug/umbrella/blob/main/services/api/database.py): `services/api/database.py`
- [AMR Training API](https://github.com/frosty-mug/umbrella/blob/main/services/api/amr_pipeline_router.py): `services/api/amr_pipeline_router.py`
- [Competitor and Stress APIs](https://github.com/frosty-mug/umbrella/tree/main/services/api): `services/api`
- [Vella Orchestrator](https://github.com/frosty-mug/umbrella/blob/main/services/vella/orchestrator.py): `services/vella/orchestrator.py`

### Bioinformatics

- [FASTA Parsing and QC](https://github.com/frosty-mug/umbrella/blob/main/core/bio/fasta_parser.py): `core/bio/fasta_parser.py`
- [AMR Annotation](https://github.com/frosty-mug/umbrella/blob/main/core/bio/amrfinder.py): `core/bio/amrfinder.py`

### AMR Modeling

- [AMR Feature Extraction](https://github.com/frosty-mug/umbrella/blob/main/ml/features/extractor.py): `ml/features/extractor.py`
- [Model Training](https://github.com/frosty-mug/umbrella/blob/main/ml/training/train_baseline.py): `ml/training/train_baseline.py`
- [Model Registry](https://github.com/frosty-mug/umbrella/blob/main/ml/registry/model_store.py): `ml/registry/model_store.py`

### Other components

- **Researcher**
- **AI Model Providers**

## Connections

- Researcher → Desktop Shell: opens desktop
- Desktop Shell → Windowing and Launcher: renders windows (evidence: `apps/desktop/app/page.tsx`)
- Desktop Shell → Window and Sample State: reads window state (evidence: `apps/desktop/app/page.tsx`)
- Desktop Shell → Clearance Login: renders clearance (evidence: `apps/desktop/app/page.tsx`)
- Window and Sample State → Windowing and Launcher: tracks window state (evidence: `apps/desktop/components/desktop/WindowFrame.tsx`)
- Desktop Shell → Genome Analysis Apps: dispatches app (evidence: `apps/desktop/app/page.tsx`)
- Desktop Shell → Genome Competitor: dispatches app (evidence: `apps/desktop/app/page.tsx`)
- Desktop Shell → Sequence QC: dispatches app (evidence: `apps/desktop/app/page.tsx`)
- Desktop Shell → Sample Vault: dispatches app (evidence: `apps/desktop/app/page.tsx`)
- Desktop Shell → Cohort Analytics: dispatches app (evidence: `apps/desktop/app/page.tsx`)
- Desktop Shell → Stress Simulators: dispatches app (evidence: `apps/desktop/app/page.tsx`)
- Desktop Shell → Science Lab: dispatches app (evidence: `apps/desktop/app/page.tsx`)
- Desktop Shell → Research Desk: dispatches app (evidence: `apps/desktop/app/page.tsx`)
- Desktop Shell → Bio-Terminal: dispatches app (evidence: `apps/desktop/app/page.tsx`)
- Desktop Shell → Reports and Export: dispatches app (evidence: `apps/desktop/app/page.tsx`)
- Desktop Shell → Vella Assistant: dispatches app (evidence: `apps/desktop/app/page.tsx`)
- Researcher → Sample Vault: selects sample
- Researcher → Sequence QC: uploads FASTA
- FastAPI Service → FASTA Parsing and QC: runs sequence QC (evidence: `services/api/main.py`)
- FastAPI Service → Database and Domain Records: persists records (evidence: `services/api/main.py`)
- FastAPI Service → Authentication and Roles: mounts routes (evidence: `services/api/main.py`)
- FastAPI Service → AMR Training API: mounts routes (evidence: `services/api/main.py`)
- FastAPI Service → Competitor and Stress APIs: mounts routes (evidence: `services/api/main.py`)
- FastAPI Service → Vella Orchestrator: dispatches requests (evidence: `services/api/main.py`)
- FASTA Parsing and QC → AMR Annotation: provides sequence input
- AMR Annotation → AMR Feature Extraction: provides annotations (evidence: `ml/features/extractor.py`)
- Model Training → AMR Feature Extraction: extracts features (evidence: `ml/training/train_baseline.py`)
- AMR Training API → Authentication and Roles: checks role (evidence: `services/api/amr_pipeline_router.py`)
- Vella Orchestrator → AI Model Providers: requests AI response (evidence: `services/vella/orchestrator.py`)
- Researcher → Cohort Analytics: explores cohorts
- Researcher → Stress Simulators: runs simulations
- Researcher → Research Desk: records investigation
- Researcher → Reports and Export: exports dossier
- Model Training → Model Registry: registers models
