# sonusajith/ossustain architecture

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

- Interactive diagram: https://gitdiagram.com/sonusajith/ossustain
- Repository: https://github.com/sonusajith/ossustain

## Overview

OSSustain is a research system for early warning of contribution-activity decline in public GitHub repositories. Its workflow selects a cohort, collects repository and collaboration history, validates quality, builds snapshots and labels, then trains/evaluates models and produces predictions for the dashboard. The Spring API serves stored repository and research results; the React app presents cohort, repository-detail, research-results, and methodology views. Pipeline stage ordering and dashboard capabilities are documented in the README; some stage internals and backend analytics implementations were not sampled, so their internal connections are omitted.

Main entry points: [`pipeline/src/ossustain_pipeline/cli.py`](https://github.com/sonusajith/ossustain/blob/main/pipeline/src/ossustain_pipeline/cli.py) (Pipeline CLI), [`frontend/src/App.tsx`](https://github.com/sonusajith/ossustain/blob/main/frontend/src/App.tsx) (Dashboard routing), [`pipeline/src/ossustain_pipeline/github/client.py`](https://github.com/sonusajith/ossustain/blob/main/pipeline/src/ossustain_pipeline/github/client.py) (GitHub REST client), [`pipeline/src/ossustain_pipeline/collect/runner.py`](https://github.com/sonusajith/ossustain/blob/main/pipeline/src/ossustain_pipeline/collect/runner.py) (Repository collection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pipeline["Research pipeline"]
  node_cli["Pipeline CLI<br/>[cli.py]"]
  node_cohort["Cohort selection<br/>[cohort.py]"]
  node_repository_collection["Repository collection<br/>[runner.py]"]
  node_collaboration["Collaboration collection<br/>[collaboration.py]"]
  node_github["GitHub REST client<br/>[client.py]"]
  node_cache["Privacy-filtered cache<br/>[cache.py]"]
  node_collection_store["Collection storage<br/>[store.py]"]
  node_validation["Collection validation<br/>[validation.py]"]
  node_features["Feature generation<br/>[runner.py]"]
  node_snapshots["Snapshots and labels<br/>[runner.py]"]
  node_modeling["Model training and evaluation<br/>[runner.py]"]
  node_predictions["Prediction generation<br/>[runner.py]"]
end

subgraph group_api["Read API"]
  node_app["API application"]
  node_repository_api["Repository endpoints"]
  node_repository_reads["Repository reads"]
  node_analytics_reads["Repository analytics"]
  node_research_api["Research endpoints"]
  node_research_reads["Research reads"]
end

subgraph group_dashboard["Dashboard"]
  node_frontend_app["Dashboard routing<br/>[App.tsx]"]
  node_cohort_view["Cohort overview<br/>[CohortOverview.tsx]"]
  node_repository_view["Repository detail"]
  node_research_view["Research results"]
  node_methodology_view["Methodology view"]
  node_api_queries["API query hooks<br/>[queries.ts]"]
  node_api_client["API client<br/>[client.ts]"]
end

node_researcher(("Researcher"))
node_postgres[("PostgreSQL")]
node_github_service{{"GitHub API"}}

node_researcher -->|"runs stages"| node_cli
node_cli -->|"selects cohort"| node_cohort
node_cli -->|"runs collection"| node_repository_collection
node_cli -->|"runs collection"| node_collaboration
node_cli -->|"runs validation"| node_validation
node_cli -->|"runs features"| node_features
node_cli -->|"builds snapshots"| node_snapshots
node_cli -->|"runs modeling"| node_modeling
node_cli -->|"generates predictions"| node_predictions
node_repository_collection -.->|"requests history"| node_github
node_collaboration -.->|"requests collaboration"| node_github
node_github -->|"sends REST requests"| node_github_service
node_github -->|"reads cached responses"| node_cache
node_repository_collection -->|"stores progress"| node_collection_store
node_collaboration -->|"stores collection"| node_collection_store
node_validation -.->|"checks collected data"| node_postgres
node_snapshots -->|"reads collection"| node_postgres
node_modeling -->|"persists results"| node_postgres
node_predictions -.->|"stores predictions"| node_postgres
node_researcher -->|"views dashboard"| node_frontend_app
node_frontend_app -->|"routes to"| node_cohort_view
node_frontend_app -->|"routes to"| node_repository_view
node_frontend_app -->|"routes to"| node_research_view
node_frontend_app -->|"routes to"| node_methodology_view
node_repository_view -->|"loads repository data"| node_api_queries
node_research_view -->|"loads results"| node_api_queries
node_api_queries -->|"calls API"| node_api_client
node_api_client -.->|"requests repository data"| node_repository_api
node_api_client -.->|"requests research data"| node_research_api
node_repository_api -->|"delegates repository reads"| node_repository_reads
node_repository_api -->|"delegates analytics"| node_analytics_reads
node_research_api -->|"delegates research reads"| node_research_reads
node_repository_reads -.->|"queries repository data"| node_postgres
node_analytics_reads -.->|"queries analytics"| node_postgres
node_research_reads -->|"queries research data"| node_postgres

click node_cli "https://github.com/sonusajith/ossustain/blob/main/pipeline/src/ossustain_pipeline/cli.py"
click node_cohort "https://github.com/sonusajith/ossustain/blob/main/pipeline/src/ossustain_pipeline/cohort.py"
click node_repository_collection "https://github.com/sonusajith/ossustain/blob/main/pipeline/src/ossustain_pipeline/collect/runner.py"
click node_collaboration "https://github.com/sonusajith/ossustain/blob/main/pipeline/src/ossustain_pipeline/collect/collaboration.py"
click node_github "https://github.com/sonusajith/ossustain/blob/main/pipeline/src/ossustain_pipeline/github/client.py"
click node_cache "https://github.com/sonusajith/ossustain/blob/main/pipeline/src/ossustain_pipeline/github/cache.py"
click node_collection_store "https://github.com/sonusajith/ossustain/blob/main/pipeline/src/ossustain_pipeline/collect/store.py"
click node_validation "https://github.com/sonusajith/ossustain/blob/main/pipeline/src/ossustain_pipeline/collect/validation.py"
click node_features "https://github.com/sonusajith/ossustain/blob/main/pipeline/src/ossustain_pipeline/features/runner.py"
click node_snapshots "https://github.com/sonusajith/ossustain/blob/main/pipeline/src/ossustain_pipeline/snapshots/runner.py"
click node_modeling "https://github.com/sonusajith/ossustain/blob/main/pipeline/src/ossustain_pipeline/modeling/runner.py"
click node_predictions "https://github.com/sonusajith/ossustain/blob/main/pipeline/src/ossustain_pipeline/predictions/runner.py"
click node_app "https://github.com/sonusajith/ossustain/blob/main/backend/src/main/java/org/ossustain/OssustainApplication.java"
click node_repository_api "https://github.com/sonusajith/ossustain/blob/main/backend/src/main/java/org/ossustain/api/repository/RepositoryController.java"
click node_repository_reads "https://github.com/sonusajith/ossustain/blob/main/backend/src/main/java/org/ossustain/api/repository/RepositoryReadService.java"
click node_analytics_reads "https://github.com/sonusajith/ossustain/blob/main/backend/src/main/java/org/ossustain/api/repository/RepositoryAnalyticsReadService.java"
click node_research_api "https://github.com/sonusajith/ossustain/blob/main/backend/src/main/java/org/ossustain/api/research/ResearchController.java"
click node_research_reads "https://github.com/sonusajith/ossustain/blob/main/backend/src/main/java/org/ossustain/api/research/ResearchReadService.java"
click node_frontend_app "https://github.com/sonusajith/ossustain/blob/main/frontend/src/App.tsx"
click node_cohort_view "https://github.com/sonusajith/ossustain/blob/main/frontend/src/features/cohort/CohortOverview.tsx"
click node_repository_view "https://github.com/sonusajith/ossustain/blob/main/frontend/src/features/repository/RepositoryDetailPage.tsx"
click node_research_view "https://github.com/sonusajith/ossustain/blob/main/frontend/src/features/research/ResearchResultsPage.tsx"
click node_methodology_view "https://github.com/sonusajith/ossustain/blob/main/frontend/src/features/research/MethodologyPage.tsx"
click node_api_queries "https://github.com/sonusajith/ossustain/blob/main/frontend/src/api/queries.ts"
click node_api_client "https://github.com/sonusajith/ossustain/blob/main/frontend/src/api/client.ts"

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,node_cohort,node_repository_collection,node_collaboration,node_github,node_cache,node_collection_store,node_validation,node_features,node_snapshots,node_modeling,node_predictions toneBlue
class node_app,node_repository_api,node_repository_reads,node_analytics_reads,node_research_api,node_research_reads,node_postgres toneAmber
class node_frontend_app,node_cohort_view,node_repository_view,node_research_view,node_methodology_view,node_api_queries,node_api_client,node_github_service toneMint
class node_researcher toneIndigo
```

## Components

### Research pipeline

- [Pipeline CLI](https://github.com/sonusajith/ossustain/blob/main/pipeline/src/ossustain_pipeline/cli.py): `pipeline/src/ossustain_pipeline/cli.py`
- [Cohort selection](https://github.com/sonusajith/ossustain/blob/main/pipeline/src/ossustain_pipeline/cohort.py): `pipeline/src/ossustain_pipeline/cohort.py`
- [Repository collection](https://github.com/sonusajith/ossustain/blob/main/pipeline/src/ossustain_pipeline/collect/runner.py): `pipeline/src/ossustain_pipeline/collect/runner.py`
- [Collaboration collection](https://github.com/sonusajith/ossustain/blob/main/pipeline/src/ossustain_pipeline/collect/collaboration.py): `pipeline/src/ossustain_pipeline/collect/collaboration.py`
- [GitHub REST client](https://github.com/sonusajith/ossustain/blob/main/pipeline/src/ossustain_pipeline/github/client.py): `pipeline/src/ossustain_pipeline/github/client.py`
- [Privacy-filtered cache](https://github.com/sonusajith/ossustain/blob/main/pipeline/src/ossustain_pipeline/github/cache.py): `pipeline/src/ossustain_pipeline/github/cache.py`
- [Collection storage](https://github.com/sonusajith/ossustain/blob/main/pipeline/src/ossustain_pipeline/collect/store.py): `pipeline/src/ossustain_pipeline/collect/store.py`
- [Collection validation](https://github.com/sonusajith/ossustain/blob/main/pipeline/src/ossustain_pipeline/collect/validation.py): `pipeline/src/ossustain_pipeline/collect/validation.py`
- [Feature generation](https://github.com/sonusajith/ossustain/blob/main/pipeline/src/ossustain_pipeline/features/runner.py): `pipeline/src/ossustain_pipeline/features/runner.py`
- [Snapshots and labels](https://github.com/sonusajith/ossustain/blob/main/pipeline/src/ossustain_pipeline/snapshots/runner.py): `pipeline/src/ossustain_pipeline/snapshots/runner.py`
- [Model training and evaluation](https://github.com/sonusajith/ossustain/blob/main/pipeline/src/ossustain_pipeline/modeling/runner.py): `pipeline/src/ossustain_pipeline/modeling/runner.py`
- [Prediction generation](https://github.com/sonusajith/ossustain/blob/main/pipeline/src/ossustain_pipeline/predictions/runner.py): `pipeline/src/ossustain_pipeline/predictions/runner.py`

### Read API

- [API application](https://github.com/sonusajith/ossustain/blob/main/backend/src/main/java/org/ossustain/OssustainApplication.java): `backend/src/main/java/org/ossustain/OssustainApplication.java`
- [Repository endpoints](https://github.com/sonusajith/ossustain/blob/main/backend/src/main/java/org/ossustain/api/repository/RepositoryController.java): `backend/src/main/java/org/ossustain/api/repository/RepositoryController.java`
- [Repository reads](https://github.com/sonusajith/ossustain/blob/main/backend/src/main/java/org/ossustain/api/repository/RepositoryReadService.java): `backend/src/main/java/org/ossustain/api/repository/RepositoryReadService.java`
- [Repository analytics](https://github.com/sonusajith/ossustain/blob/main/backend/src/main/java/org/ossustain/api/repository/RepositoryAnalyticsReadService.java): `backend/src/main/java/org/ossustain/api/repository/RepositoryAnalyticsReadService.java`
- [Research endpoints](https://github.com/sonusajith/ossustain/blob/main/backend/src/main/java/org/ossustain/api/research/ResearchController.java): `backend/src/main/java/org/ossustain/api/research/ResearchController.java`
- [Research reads](https://github.com/sonusajith/ossustain/blob/main/backend/src/main/java/org/ossustain/api/research/ResearchReadService.java): `backend/src/main/java/org/ossustain/api/research/ResearchReadService.java`

### Dashboard

- [Dashboard routing](https://github.com/sonusajith/ossustain/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Cohort overview](https://github.com/sonusajith/ossustain/blob/main/frontend/src/features/cohort/CohortOverview.tsx): `frontend/src/features/cohort/CohortOverview.tsx`
- [Repository detail](https://github.com/sonusajith/ossustain/blob/main/frontend/src/features/repository/RepositoryDetailPage.tsx): `frontend/src/features/repository/RepositoryDetailPage.tsx`
- [Research results](https://github.com/sonusajith/ossustain/blob/main/frontend/src/features/research/ResearchResultsPage.tsx): `frontend/src/features/research/ResearchResultsPage.tsx`
- [Methodology view](https://github.com/sonusajith/ossustain/blob/main/frontend/src/features/research/MethodologyPage.tsx): `frontend/src/features/research/MethodologyPage.tsx`
- [API query hooks](https://github.com/sonusajith/ossustain/blob/main/frontend/src/api/queries.ts): `frontend/src/api/queries.ts`
- [API client](https://github.com/sonusajith/ossustain/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`

### Other components

- **Researcher**
- **PostgreSQL**
- **GitHub API**

## Connections

- Researcher → Pipeline CLI: runs stages (evidence: `README.md`)
- Pipeline CLI → Cohort selection: selects cohort (evidence: `pipeline/src/ossustain_pipeline/cli.py`)
- Pipeline CLI → Repository collection: runs collection (evidence: `pipeline/src/ossustain_pipeline/cli.py`)
- Pipeline CLI → Collaboration collection: runs collection (evidence: `pipeline/src/ossustain_pipeline/cli.py`)
- Pipeline CLI → Collection validation: runs validation (evidence: `pipeline/src/ossustain_pipeline/cli.py`)
- Pipeline CLI → Feature generation: runs features (evidence: `pipeline/src/ossustain_pipeline/cli.py`)
- Pipeline CLI → Snapshots and labels: builds snapshots (evidence: `pipeline/src/ossustain_pipeline/cli.py`)
- Pipeline CLI → Model training and evaluation: runs modeling (evidence: `pipeline/src/ossustain_pipeline/cli.py`)
- Pipeline CLI → Prediction generation: generates predictions (evidence: `pipeline/src/ossustain_pipeline/cli.py`)
- Repository collection → GitHub REST client: requests history
- Collaboration collection → GitHub REST client: requests collaboration
- GitHub REST client → GitHub API: sends REST requests (evidence: `pipeline/src/ossustain_pipeline/github/client.py`)
- GitHub REST client → Privacy-filtered cache: reads cached responses (evidence: `pipeline/src/ossustain_pipeline/github/client.py`)
- Repository collection → Collection storage: stores progress (evidence: `README.md`)
- Collaboration collection → Collection storage: stores collection (evidence: `README.md`)
- Collection validation → PostgreSQL: checks collected data
- Snapshots and labels → PostgreSQL: reads collection (evidence: `README.md`)
- Model training and evaluation → PostgreSQL: persists results (evidence: `pipeline/src/ossustain_pipeline/modeling/runner.py`)
- Prediction generation → PostgreSQL: stores predictions
- Researcher → Dashboard routing: views dashboard (evidence: `README.md`)
- Dashboard routing → Cohort overview: routes to (evidence: `frontend/src/App.tsx`)
- Dashboard routing → Repository detail: routes to (evidence: `frontend/src/App.tsx`)
- Dashboard routing → Research results: routes to (evidence: `frontend/src/App.tsx`)
- Dashboard routing → Methodology view: routes to (evidence: `frontend/src/App.tsx`)
- Repository detail → API query hooks: loads repository data (evidence: `frontend/src/features/repository/RepositoryDetailPage.tsx`)
- Research results → API query hooks: loads results (evidence: `frontend/src/features/research/ResearchResultsPage.tsx`)
- API query hooks → API client: calls API (evidence: `frontend/src/api/queries.ts`)
- API client → Repository endpoints: requests repository data
- API client → Research endpoints: requests research data
- Repository endpoints → Repository reads: delegates repository reads (evidence: `backend/src/main/java/org/ossustain/api/repository/RepositoryController.java`)
- Repository endpoints → Repository analytics: delegates analytics (evidence: `backend/src/main/java/org/ossustain/api/repository/RepositoryController.java`)
- Research endpoints → Research reads: delegates research reads (evidence: `backend/src/main/java/org/ossustain/api/research/ResearchController.java`)
- Repository reads → PostgreSQL: queries repository data
- Repository analytics → PostgreSQL: queries analytics
- Research reads → PostgreSQL: queries research data (evidence: `backend/src/main/java/org/ossustain/api/research/ResearchReadService.java`)
