# acdeveloper-sci/fortriage architecture

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

- Interactive diagram: https://gitdiagram.com/acdeveloper-sci/fortriage
- Repository: https://github.com/acdeveloper-sci/fortriage

## Overview

#### Purpose and Entry Points
ForTriage is an ephemeral Streamlit dashboard for prioritizing modernization risk in legacy Fortran systems. It consumes curated Forti4D analysis outputs, rather than parsing or modifying source itself. The process starts at `streamlit_app.py`, which delegates application initialization and navigation to `fortriage/app.py`.

#### Application Shell and Session State
The app shell owns Streamlit page routing, shared initialization, and the active-analysis lifecycle. Session-scoped state keeps uploaded/generated analysis available across dashboard pages without a database or cross-session persistence. Key paths: `fortriage/app.py`, `fortriage/state.py`, `fortriage/config.py`.

#### Upload and Analysis Boundary
Users provide a project/archive; the upload layer validates and stages it, while the pipeline invokes or consumes Forti4D analysis and converts its reports into dashboard-ready structures. Forti4D is an external, independent static-analysis engine and is the boundary for Fortran parsing, metrics, dependency analysis, and source-level risk computation. Key paths: `fortriage/uploads.py`, `fortriage/pipeline.py`, `test_pipeline_manual.py`.

#### Prioritized Analysis Model
The pipeline’s curated report corpus drives the application’s risk-ranked unit views: complexity, reachability/dead code, clones, coupling, dependencies, and score breakdowns. This is the central data boundary: UI code should consume normalized analysis results, not Forti4D internal diagnostics such as per-file audit/block dumps. Key paths: `fortriage/pipeline.py`, `fortriage/state.py`, `fortriage/config.py`.

#### Dashboard Exploration Views
Streamlit views present the same session analysis through complementary decision workflows: system-level prioritization, per-unit inspection, management-facing synthesis, and raw curated-report exploration. Navigation and selections should hand off through shared state rather than recomputing analysis. Key paths: `fortriage/views/overview.py`, `fortriage/views/drilldown.py`, `fortriage/views/executive_summary.py`, `fortriage/views/report_explorer.py`.

#### Visualization and Reusable UI
Shared components provide charts, risk/status badges, metric presentation, and unit-detail modal interactions; they are presentation-layer consumers of normalized analysis data. Altair is the material visualization runtime, embedded within Streamlit. Key paths: `fortriage/components/charts.py`, `fortriage/components/metric_bar.py`, `fortriage/components/unit_modal.py`.

#### AI Insights and External Service Boundary
AI Insights builds constrained context from aggregated reports and executive/prioritization findings, assembles prompt assets, and calls Google Gemini only when configured. It must not send raw Fortran source; non-AI dashboard functionality remains offline. Gemini credentials come from Streamlit secrets, and the feature degrades when no API key is available. Key paths: `fortriage/views/ai_insights.py`, `fortriage/insights_context.py`, `fortriage/gemini_client.py`, `fortriage/prompts.py`.

#### Runtime and Infrastructure
The runtime is Python 3.10+ with Streamlit, launched through `uv run streamlit run streamlit_app.py`; dependency resolution is defined by `pyproject.toml` and `uv.lock`. Deployment configuration is Streamlit-local in `.streamlit/config.toml`. No database, persistent project store, or cloud analysis backend is present; the only runtime external service is optional Google Gemini, while Forti4D remains an external analysis dependency.

Main entry points: [`fortriage/app.py`](https://github.com/acdeveloper-sci/fortriage/blob/main/fortriage/app.py) (App routing), [`fortriage/state.py`](https://github.com/acdeveloper-sci/fortriage/blob/main/fortriage/state.py) (Session analysis), [`fortriage/pipeline.py`](https://github.com/acdeveloper-sci/fortriage/blob/main/fortriage/pipeline.py) (Analysis pipeline), [`fortriage/components/charts.py`](https://github.com/acdeveloper-sci/fortriage/blob/main/fortriage/components/charts.py) (Shared UI components)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App shell"]
  node_entry["Streamlit entry<br/>Python entrypoint<br/>[streamlit_app.py]"]
  node_shell["App routing<br/>Streamlit shell<br/>[app.py]"]
  node_state[("Session analysis<br/>session state<br/>[state.py]")]
  node_config["App configuration<br/>[config.py]"]
end

subgraph group_analysis["Analysis workflow"]
  node_upload["Upload staging<br/>upload boundary<br/>[uploads.py]"]
  node_pipeline["Analysis pipeline<br/>report pipeline<br/>[pipeline.py]"]
  node_forti4d{{"Forti4D<br/>external analyzer"}}
  node_report_model[("Curated report model<br/>normalized analysis<br/>[pipeline.py]")]
end

subgraph group_views["Dashboard views"]
  node_overview["Overview<br/>dashboard view<br/>[overview.py]"]
  node_drilldown["Unit drilldown<br/>dashboard view<br/>[drilldown.py]"]
  node_executive["Executive summary<br/>dashboard view"]
  node_reports["Report explorer<br/>dashboard view<br/>[report_explorer.py]"]
  node_components["Shared UI components<br/>presentation layer<br/>[charts.py]"]
  node_altair{{"Altair<br/>visualization runtime"}}
end

subgraph group_ai["Optional AI insights"]
  node_insights_view["AI Insights view<br/>dashboard view<br/>[ai_insights.py]"]
  node_insights_context["Constrained context<br/>insight context"]
  node_prompts["Prompt assets<br/>prompt templates<br/>[prompts.py]"]
  node_gemini_client["Gemini client<br/>AI service client<br/>[gemini_client.py]"]
  node_gemini{{"Google Gemini<br/>external AI service"}}
end

node_runtime["Python / Streamlit runtime<br/>runtime environment<br/>[pyproject.toml]"]

node_entry -->|"starts"| node_shell
node_runtime -->|"runs"| node_entry
node_shell -->|"initializes"| node_state
node_shell -->|"reads"| node_config
node_shell -->|"routes to"| node_upload
node_upload -->|"staged project"| node_pipeline
node_pipeline -->|"invokes or consumes reports"| node_forti4d
node_forti4d -->|"analysis outputs"| node_pipeline
node_pipeline -->|"normalizes"| node_report_model
node_report_model -->|"stored for session"| node_state
node_shell -->|"routes to"| node_overview
node_shell -->|"routes to"| node_drilldown
node_shell -->|"routes to"| node_executive
node_shell -->|"routes to"| node_reports
node_state -->|"shared analysis"| node_overview
node_state -->|"shared analysis and selection"| node_drilldown
node_state -->|"shared analysis"| node_executive
node_state -->|"shared analysis"| node_reports
node_overview -->|"renders with"| node_components
node_drilldown -->|"renders with"| node_components
node_executive -->|"renders with"| node_components
node_components -->|"charts"| node_altair
node_shell -->|"routes to"| node_insights_view
node_state -->|"aggregated findings"| node_insights_view
node_insights_view -->|"builds"| node_insights_context
node_insights_context -->|"constrains input"| node_prompts
node_prompts -->|"assembled request"| node_gemini_client
node_gemini_client -.->|"optional API call"| node_gemini

click node_entry "https://github.com/acdeveloper-sci/fortriage/blob/main/streamlit_app.py"
click node_shell "https://github.com/acdeveloper-sci/fortriage/blob/main/fortriage/app.py"
click node_state "https://github.com/acdeveloper-sci/fortriage/blob/main/fortriage/state.py"
click node_config "https://github.com/acdeveloper-sci/fortriage/blob/main/fortriage/config.py"
click node_upload "https://github.com/acdeveloper-sci/fortriage/blob/main/fortriage/uploads.py"
click node_pipeline "https://github.com/acdeveloper-sci/fortriage/blob/main/fortriage/pipeline.py"
click node_report_model "https://github.com/acdeveloper-sci/fortriage/blob/main/fortriage/pipeline.py"
click node_overview "https://github.com/acdeveloper-sci/fortriage/blob/main/fortriage/views/overview.py"
click node_drilldown "https://github.com/acdeveloper-sci/fortriage/blob/main/fortriage/views/drilldown.py"
click node_executive "https://github.com/acdeveloper-sci/fortriage/blob/main/fortriage/views/executive_summary.py"
click node_reports "https://github.com/acdeveloper-sci/fortriage/blob/main/fortriage/views/report_explorer.py"
click node_components "https://github.com/acdeveloper-sci/fortriage/blob/main/fortriage/components/charts.py"
click node_insights_view "https://github.com/acdeveloper-sci/fortriage/blob/main/fortriage/views/ai_insights.py"
click node_insights_context "https://github.com/acdeveloper-sci/fortriage/blob/main/fortriage/insights_context.py"
click node_prompts "https://github.com/acdeveloper-sci/fortriage/blob/main/fortriage/prompts.py"
click node_gemini_client "https://github.com/acdeveloper-sci/fortriage/blob/main/fortriage/gemini_client.py"
click node_runtime "https://github.com/acdeveloper-sci/fortriage/blob/main/pyproject.toml"

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_entry,node_shell,node_state,node_config toneBlue
class node_upload,node_pipeline,node_forti4d,node_report_model toneAmber
class node_overview,node_drilldown,node_executive,node_reports,node_components,node_altair toneMint
class node_insights_view,node_insights_context,node_prompts,node_gemini_client,node_gemini toneRose
class node_runtime toneNeutral
```

## Components

### App shell

- [Streamlit entry](https://github.com/acdeveloper-sci/fortriage/blob/main/streamlit_app.py): Python entrypoint · `streamlit_app.py`
- [App routing](https://github.com/acdeveloper-sci/fortriage/blob/main/fortriage/app.py): Streamlit shell · Initializes the app and routes pages. · `fortriage/app.py`
- [Session analysis](https://github.com/acdeveloper-sci/fortriage/blob/main/fortriage/state.py): session state · Ephemeral shared analysis and selections. · `fortriage/state.py`
- [App configuration](https://github.com/acdeveloper-sci/fortriage/blob/main/fortriage/config.py): configuration · `fortriage/config.py`

### Analysis workflow

- [Upload staging](https://github.com/acdeveloper-sci/fortriage/blob/main/fortriage/uploads.py): upload boundary · Validates and stages user projects or archives. · `fortriage/uploads.py`
- [Analysis pipeline](https://github.com/acdeveloper-sci/fortriage/blob/main/fortriage/pipeline.py): report pipeline · Converts Forti4D outputs into dashboard-ready results. · `fortriage/pipeline.py`
- **Forti4D**: external analyzer · Independent Fortran parsing, metrics, dependency, and risk engine.
- [Curated report model](https://github.com/acdeveloper-sci/fortriage/blob/main/fortriage/pipeline.py): normalized analysis · Risk-ranked units, scores, dependencies, clones, and reachability. · `fortriage/pipeline.py`

### Dashboard views

- [Overview](https://github.com/acdeveloper-sci/fortriage/blob/main/fortriage/views/overview.py): dashboard view · `fortriage/views/overview.py`
- [Unit drilldown](https://github.com/acdeveloper-sci/fortriage/blob/main/fortriage/views/drilldown.py): dashboard view · `fortriage/views/drilldown.py`
- [Executive summary](https://github.com/acdeveloper-sci/fortriage/blob/main/fortriage/views/executive_summary.py): dashboard view · `fortriage/views/executive_summary.py`
- [Report explorer](https://github.com/acdeveloper-sci/fortriage/blob/main/fortriage/views/report_explorer.py): dashboard view · `fortriage/views/report_explorer.py`
- [Shared UI components](https://github.com/acdeveloper-sci/fortriage/blob/main/fortriage/components/charts.py): presentation layer · Charts, badges, metrics, and unit-detail interactions. · `fortriage/components/charts.py`
- **Altair**: visualization runtime

### Optional AI insights

- [AI Insights view](https://github.com/acdeveloper-sci/fortriage/blob/main/fortriage/views/ai_insights.py): dashboard view · Remains unavailable when Gemini is not configured. · `fortriage/views/ai_insights.py`
- [Constrained context](https://github.com/acdeveloper-sci/fortriage/blob/main/fortriage/insights_context.py): insight context · Builds aggregated report and prioritization context without source. · `fortriage/insights_context.py`
- [Prompt assets](https://github.com/acdeveloper-sci/fortriage/blob/main/fortriage/prompts.py): prompt templates · `fortriage/prompts.py`
- [Gemini client](https://github.com/acdeveloper-sci/fortriage/blob/main/fortriage/gemini_client.py): AI service client · Uses Streamlit secrets for optional credentials. · `fortriage/gemini_client.py`
- **Google Gemini**: external AI service

### Other components

- [Python / Streamlit runtime](https://github.com/acdeveloper-sci/fortriage/blob/main/pyproject.toml): runtime environment · Launched with uv and dependency resolution. · `pyproject.toml`

## Connections

- Streamlit entry → App routing: starts
- Python / Streamlit runtime → Streamlit entry: runs
- App routing → Session analysis: initializes
- App routing → App configuration: reads
- App routing → Upload staging: routes to
- Upload staging → Analysis pipeline: staged project
- Analysis pipeline → Forti4D: invokes or consumes reports
- Forti4D → Analysis pipeline: analysis outputs
- Analysis pipeline → Curated report model: normalizes
- Curated report model → Session analysis: stored for session
- App routing → Overview: routes to
- App routing → Unit drilldown: routes to
- App routing → Executive summary: routes to
- App routing → Report explorer: routes to
- Session analysis → Overview: shared analysis
- Session analysis → Unit drilldown: shared analysis and selection
- Session analysis → Executive summary: shared analysis
- Session analysis → Report explorer: shared analysis
- Overview → Shared UI components: renders with
- Unit drilldown → Shared UI components: renders with
- Executive summary → Shared UI components: renders with
- Shared UI components → Altair: charts
- App routing → AI Insights view: routes to
- Session analysis → AI Insights view: aggregated findings
- AI Insights view → Constrained context: builds
- Constrained context → Prompt assets: constrains input
- Prompt assets → Gemini client: assembled request
- Gemini client → Google Gemini: optional API call