# aiforhpc/astraai architecture

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

- Interactive diagram: https://gitdiagram.com/aiforhpc/astraai
- Repository: https://github.com/aiforhpc/astraai

## Overview

AstraAI is a Linux CLI and GitHub-PR assistant for HPC C++ and Fortran code. Its documented workflow takes a user request, adds retrieval- and AST-derived context for code assistance, then generates or explains a result; a PR watcher also supports requests in GitHub conversations. The repository additionally documents standalone inference and Hugging Face model fine-tuning. Source excerpts show parts of C++ retrieval, code advising and modification, but not the full dispatcher or the Fortran watcher flow, so those connections are not inferred.

Main entry points: [`AstraAI/AstraAI_cpp/astraai.py`](https://github.com/aiforhpc/astraai/blob/main/AstraAI/AstraAI_cpp/astraai.py) (C++ CLI), [`AstraAI/AstraAI_cpp/rag.py`](https://github.com/aiforhpc/astraai/blob/main/AstraAI/AstraAI_cpp/rag.py) (RAG retrieval), [`AstraAI/AstraAI_fortran/pr_watcher.py`](https://github.com/aiforhpc/astraai/blob/main/AstraAI/AstraAI_fortran/pr_watcher.py) (PR watcher), [`AstraAI/AstraAI_cpp/codemodification.py`](https://github.com/aiforhpc/astraai/blob/main/AstraAI/AstraAI_cpp/codemodification.py) (Code modification)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Request entry points"]
  node_cpp_cli["C++ CLI<br/>[astraai.py]"]
  node_pr_watcher["PR watcher<br/>[pr_watcher.py]"]
end

subgraph group_cpp["C++ assistance"]
  node_intent["Intent routing<br/>[intent.py]"]
  node_code_advising["Code advising<br/>[codeadvising.py]"]
  node_modification["Code modification"]
  node_explaining["Code explaining<br/>[explaining.py]"]
end

subgraph group_context["Code context"]
  node_ast["C++ AST tools<br/>[ast_cpp.py]"]
  node_rag["RAG retrieval<br/>[rag.py]"]
  node_metadata["RAG metadata extraction"]
end

subgraph group_fortran["Fortran assistance"]
  node_fortran_help["Fortran assistance"]
  node_embeddings["Embedding utility<br/>[embeddings.py]"]
end

subgraph group_models["Models and tuning"]
  node_inference["Standalone inference"]
  node_llm["Ollama LLM access<br/>[llm.py]"]
  node_fine_tuning["Model fine-tuning<br/>[FineTuning.py]"]
end

node_user(("CLI user"))
node_github(("GitHub PR"))

node_user -->|"submits request"| node_cpp_cli
node_cpp_cli -.->|"routes requests"| node_intent
node_code_advising -->|"builds context"| node_rag
node_modification -->|"builds context"| node_rag
node_modification -->|"queries structure"| node_ast
node_rag -->|"embeds query"| node_llm
node_cpp_cli -.->|"adds AST context"| node_ast
node_cpp_cli -->|"adds RAG context"| node_rag
node_cpp_cli -->|"supports Fortran"| node_fortran_help
node_github -.->|"posts request"| node_pr_watcher
node_pr_watcher -->|"reads PRs"| node_github
node_pr_watcher -.->|"uses embeddings"| node_embeddings
node_user -->|"runs inference"| node_inference
node_user -->|"fine-tunes model"| node_fine_tuning
node_metadata -.->|"provides chunks"| node_rag

click node_cpp_cli "https://github.com/aiforhpc/astraai/blob/main/AstraAI/AstraAI_cpp/astraai.py"
click node_pr_watcher "https://github.com/aiforhpc/astraai/blob/main/AstraAI/AstraAI_fortran/pr_watcher.py"
click node_intent "https://github.com/aiforhpc/astraai/blob/main/AstraAI/AstraAI_cpp/intent.py"
click node_code_advising "https://github.com/aiforhpc/astraai/blob/main/AstraAI/AstraAI_cpp/codeadvising.py"
click node_modification "https://github.com/aiforhpc/astraai/blob/main/AstraAI/AstraAI_cpp/codemodification.py"
click node_explaining "https://github.com/aiforhpc/astraai/blob/main/AstraAI/AstraAI_cpp/explaining.py"
click node_ast "https://github.com/aiforhpc/astraai/blob/main/AstraAI/AstraAI_cpp/ast_cpp.py"
click node_rag "https://github.com/aiforhpc/astraai/blob/main/AstraAI/AstraAI_cpp/rag.py"
click node_metadata "https://github.com/aiforhpc/astraai/tree/main/RAG"
click node_fortran_help "https://github.com/aiforhpc/astraai/tree/main/AstraAI/AstraAI_fortran"
click node_embeddings "https://github.com/aiforhpc/astraai/blob/main/AstraAI/AstraAI_fortran/embeddings.py"
click node_inference "https://github.com/aiforhpc/astraai/tree/main/Inference"
click node_llm "https://github.com/aiforhpc/astraai/blob/main/AstraAI/AstraAI_cpp/llm.py"
click node_fine_tuning "https://github.com/aiforhpc/astraai/blob/main/FineTuning/FineTuning.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_cpp_cli,node_pr_watcher,node_user toneBlue
class node_intent,node_code_advising,node_modification,node_explaining toneAmber
class node_ast,node_rag,node_metadata toneMint
class node_fortran_help,node_embeddings toneRose
class node_inference,node_llm,node_fine_tuning,node_github toneIndigo
```

## Components

### Request entry points

- [C++ CLI](https://github.com/aiforhpc/astraai/blob/main/AstraAI/AstraAI_cpp/astraai.py): `AstraAI/AstraAI_cpp/astraai.py`
- [PR watcher](https://github.com/aiforhpc/astraai/blob/main/AstraAI/AstraAI_fortran/pr_watcher.py): `AstraAI/AstraAI_fortran/pr_watcher.py`

### C++ assistance

- [Intent routing](https://github.com/aiforhpc/astraai/blob/main/AstraAI/AstraAI_cpp/intent.py): `AstraAI/AstraAI_cpp/intent.py`
- [Code advising](https://github.com/aiforhpc/astraai/blob/main/AstraAI/AstraAI_cpp/codeadvising.py): `AstraAI/AstraAI_cpp/codeadvising.py`
- [Code modification](https://github.com/aiforhpc/astraai/blob/main/AstraAI/AstraAI_cpp/codemodification.py): `AstraAI/AstraAI_cpp/codemodification.py`
- [Code explaining](https://github.com/aiforhpc/astraai/blob/main/AstraAI/AstraAI_cpp/explaining.py): `AstraAI/AstraAI_cpp/explaining.py`

### Code context

- [C++ AST tools](https://github.com/aiforhpc/astraai/blob/main/AstraAI/AstraAI_cpp/ast_cpp.py): `AstraAI/AstraAI_cpp/ast_cpp.py`
- [RAG retrieval](https://github.com/aiforhpc/astraai/blob/main/AstraAI/AstraAI_cpp/rag.py): `AstraAI/AstraAI_cpp/rag.py`
- [RAG metadata extraction](https://github.com/aiforhpc/astraai/tree/main/RAG): `RAG`

### Fortran assistance

- [Fortran assistance](https://github.com/aiforhpc/astraai/tree/main/AstraAI/AstraAI_fortran): `AstraAI/AstraAI_fortran`
- [Embedding utility](https://github.com/aiforhpc/astraai/blob/main/AstraAI/AstraAI_fortran/embeddings.py): `AstraAI/AstraAI_fortran/embeddings.py`

### Models and tuning

- [Standalone inference](https://github.com/aiforhpc/astraai/tree/main/Inference): `Inference`
- [Ollama LLM access](https://github.com/aiforhpc/astraai/blob/main/AstraAI/AstraAI_cpp/llm.py): `AstraAI/AstraAI_cpp/llm.py`
- [Model fine-tuning](https://github.com/aiforhpc/astraai/blob/main/FineTuning/FineTuning.py): `FineTuning/FineTuning.py`

### Other components

- **CLI user**
- **GitHub PR**

## Connections

- CLI user → C++ CLI: submits request (evidence: `README.md`)
- C++ CLI → Intent routing: routes requests (evidence: `AstraAI/AstraAI_cpp/astraai.py`)
- Code advising → RAG retrieval: builds context (evidence: `AstraAI/AstraAI_cpp/codeadvising.py`)
- Code modification → RAG retrieval: builds context (evidence: `AstraAI/AstraAI_cpp/codemodification.py`)
- Code modification → C++ AST tools: queries structure (evidence: `AstraAI/AstraAI_cpp/codemodification.py`)
- RAG retrieval → Ollama LLM access: embeds query (evidence: `AstraAI/AstraAI_cpp/rag.py`)
- C++ CLI → C++ AST tools: adds AST context (evidence: `AstraAI/AstraAI_cpp/astraai.py`)
- C++ CLI → RAG retrieval: adds RAG context (evidence: `README.md`)
- C++ CLI → Fortran assistance: supports Fortran (evidence: `README.md`)
- GitHub PR → PR watcher: posts request
- PR watcher → GitHub PR: reads PRs (evidence: `AstraAI/AstraAI_fortran/pr_watcher.py`)
- PR watcher → Embedding utility: uses embeddings (evidence: `AstraAI/AstraAI_fortran/pr_watcher.py`)
- CLI user → Standalone inference: runs inference (evidence: `README.md`)
- CLI user → Model fine-tuning: fine-tunes model (evidence: `README.md`)
- RAG metadata extraction → RAG retrieval: provides chunks
