# whitehead/plaac architecture

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

- Interactive diagram: https://gitdiagram.com/whitehead/plaac
- Repository: https://github.com/whitehead/plaac

## Overview

PLAAC analyzes protein FASTA sequences for prion-like subsequences and returns ranked per-protein scores and candidate regions. Users can run the Java CLI directly or through the Python wrapper; the web application accepts uploads, runs jobs, and offers candidate results and visualization downloads. Background amino-acid frequencies configure analyses, and a yeast spreadsheet utility enriches result tables. The web excerpts show job setup, result handling, and visualization, but omit route and command construction details, so those links are not asserted. The web server is documented as using the same Java application as the CLI.

Main entry points: [`web/lib/server.rb`](https://github.com/whitehead/plaac/blob/master/web/lib/server.rb) (Web application), [`cli/src/plaac.java`](https://github.com/whitehead/plaac/blob/master/cli/src/plaac.java) (Java CLI), [`cli/python/src/plaac/__init__.py`](https://github.com/whitehead/plaac/blob/master/cli/python/src/plaac/__init__.py) (Python wrapper), [`web/lib/job.rb`](https://github.com/whitehead/plaac/blob/master/web/lib/job.rb) (Job runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli_engine["Java CLI<br/>[plaac.java]"]
  node_python_api["Python wrapper<br/>[__init__.py]"]
  node_web_app["Web application<br/>[server.rb]"]
end

subgraph group_analysis["Sequence analysis"]
  node_hmm_scoring["HMM scoring<br/>[plaac.java]"]
end

subgraph group_webjobs["Web jobs and results"]
  node_job_runner["Job runner<br/>[job.rb]"]
  node_job_files[("Job workspace<br/>[job.rb]")]
  node_candidate_results["Candidate results<br/>[server.rb]"]
  node_visualization["Candidate visualization<br/>[server.rb]"]
end

subgraph group_support["Analysis data and exports"]
  node_background_freqs["Background frequencies"]
  node_yeast_spreadsheet["Yeast spreadsheet export"]
end

node_cli_user(("CLI user"))
node_python_user(("Python user"))
node_web_user(("Web user"))
node_spreadsheet_user(("Spreadsheet user"))

node_cli_user -->|"runs analysis"| node_cli_engine
node_python_user -->|"calls wrapper"| node_python_api
node_python_api -->|"launches Java"| node_cli_engine
node_cli_engine -->|"scores sequences"| node_hmm_scoring
node_web_user -->|"submits sequences"| node_web_app
node_web_app -->|"creates job"| node_job_runner
node_job_runner -->|"writes job files"| node_job_files
node_web_app -->|"reads results"| node_job_files
node_web_app -->|"loads candidates"| node_candidate_results
node_web_app -->|"generates details"| node_visualization
node_web_app -->|"reads frequencies"| node_background_freqs
node_web_app -->|"uses Java analysis"| node_cli_engine
node_spreadsheet_user -->|"exports results"| node_yeast_spreadsheet
node_candidate_results -->|"enriches TSV"| node_yeast_spreadsheet

click node_cli_engine "https://github.com/whitehead/plaac/blob/master/cli/src/plaac.java"
click node_python_api "https://github.com/whitehead/plaac/blob/master/cli/python/src/plaac/__init__.py"
click node_web_app "https://github.com/whitehead/plaac/blob/master/web/lib/server.rb"
click node_hmm_scoring "https://github.com/whitehead/plaac/blob/master/cli/src/plaac.java"
click node_job_runner "https://github.com/whitehead/plaac/blob/master/web/lib/job.rb"
click node_job_files "https://github.com/whitehead/plaac/blob/master/web/lib/job.rb"
click node_candidate_results "https://github.com/whitehead/plaac/blob/master/web/lib/server.rb"
click node_visualization "https://github.com/whitehead/plaac/blob/master/web/lib/server.rb"
click node_background_freqs "https://github.com/whitehead/plaac/tree/master/web/bg_freqs"
click node_yeast_spreadsheet "https://github.com/whitehead/plaac/blob/master/web/bin/fancy-yeast-spreadsheet.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_cli_engine,node_python_api,node_web_app,node_cli_user,node_python_user,node_web_user,node_spreadsheet_user toneBlue
class node_hmm_scoring toneAmber
class node_job_runner,node_job_files,node_candidate_results,node_visualization toneMint
class node_background_freqs,node_yeast_spreadsheet toneRose
```

## Components

### User interfaces

- [Java CLI](https://github.com/whitehead/plaac/blob/master/cli/src/plaac.java): `cli/src/plaac.java`
- [Python wrapper](https://github.com/whitehead/plaac/blob/master/cli/python/src/plaac/__init__.py): `cli/python/src/plaac/__init__.py`
- [Web application](https://github.com/whitehead/plaac/blob/master/web/lib/server.rb): `web/lib/server.rb`

### Sequence analysis

- [HMM scoring](https://github.com/whitehead/plaac/blob/master/cli/src/plaac.java): `cli/src/plaac.java`

### Web jobs and results

- [Job runner](https://github.com/whitehead/plaac/blob/master/web/lib/job.rb): `web/lib/job.rb`
- [Job workspace](https://github.com/whitehead/plaac/blob/master/web/lib/job.rb): `web/lib/job.rb`
- [Candidate results](https://github.com/whitehead/plaac/blob/master/web/lib/server.rb): `web/lib/server.rb`
- [Candidate visualization](https://github.com/whitehead/plaac/blob/master/web/lib/server.rb): `web/lib/server.rb`

### Analysis data and exports

- [Background frequencies](https://github.com/whitehead/plaac/tree/master/web/bg_freqs): `web/bg_freqs`
- [Yeast spreadsheet export](https://github.com/whitehead/plaac/blob/master/web/bin/fancy-yeast-spreadsheet.py): `web/bin/fancy-yeast-spreadsheet.py`

### Other components

- **CLI user**
- **Python user**
- **Web user**
- **Spreadsheet user**

## Connections

- CLI user → Java CLI: runs analysis (evidence: `README.md`)
- Python user → Python wrapper: calls wrapper (evidence: `cli/python/src/plaac/__init__.py`)
- Python wrapper → Java CLI: launches Java (evidence: `cli/python/src/plaac/__init__.py`)
- Java CLI → HMM scoring: scores sequences (evidence: `cli/src/plaac.java`)
- Web user → Web application: submits sequences (evidence: `README.md`)
- Web application → Job runner: creates job (evidence: `web/lib/server.rb`)
- Job runner → Job workspace: writes job files (evidence: `web/lib/job.rb`)
- Web application → Job workspace: reads results (evidence: `web/lib/server.rb`)
- Web application → Candidate results: loads candidates (evidence: `web/lib/server.rb`)
- Web application → Candidate visualization: generates details (evidence: `web/lib/server.rb`)
- Web application → Background frequencies: reads frequencies (evidence: `web/lib/server.rb`)
- Web application → Java CLI: uses Java analysis (evidence: `README.md`)
- Spreadsheet user → Yeast spreadsheet export: exports results (evidence: `web/bin/fancy-yeast-spreadsheet.py`)
- Candidate results → Yeast spreadsheet export: enriches TSV (evidence: `web/bin/fancy-yeast-spreadsheet.py`)