# ida7jhu/csit998_group10 architecture

> Architecture diagram of the GitHub repository ida7jhu/csit998_group10, 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/ida7jhu/csit998_group10
- Repository: https://github.com/ida7jhu/csit998_group10

## Overview

n1-optimizer reads Python source without executing it, identifies inefficient database-use patterns, and suggests faster code. The user supplies a file or stdin through the CLI; the pipeline builds structured facts, optionally logs them, and requests AI suggestions when Ollama is available. The analyzer also creates deterministic SQL rewrites for patterns it recognizes, which take precedence over overlapping model findings. The tool never connects to a database. Edges follow README statements and shown imports/calls; unsampled implementation details are not inferred.

Main entry points: [`n1_optimizer/ast_builder.py`](https://github.com/ida7jhu/csit998_group10/blob/main/n1_optimizer/ast_builder.py) (Source analyzer), [`n1_optimizer/pipeline.py`](https://github.com/ida7jhu/csit998_group10/blob/main/n1_optimizer/pipeline.py) (Analysis pipeline), [`n1_optimizer/llm_optimizer.py`](https://github.com/ida7jhu/csit998_group10/blob/main/n1_optimizer/llm_optimizer.py) (Suggestion processor), [`n1_optimizer/ast_model.py`](https://github.com/ida7jhu/csit998_group10/blob/main/n1_optimizer/ast_model.py) (Procedure facts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_cli["Command-line interface<br/>[cli.py]"]
  node_pipeline["Analysis pipeline<br/>[pipeline.py]"]
end

subgraph group_analysis["Static analysis"]
  node_ast_builder["Source analyzer<br/>[ast_builder.py]"]
  node_ast_model["Procedure facts<br/>[ast_model.py]"]
  node_sql_facts["SQL fact helpers<br/>[sql_facts.py]"]
  node_value_sql["Value SQL helpers<br/>[value_sql.py]"]
  node_rewrites["SQL rewrite builder<br/>[rewrites.py]"]
end

subgraph group_suggestions["Optimization suggestions"]
  node_llm_optimizer["Suggestion processor<br/>[llm_optimizer.py]"]
  node_ollama_client["Ollama client<br/>[ollama_client.py]"]
end

subgraph group_observability["Run logs"]
  node_ast_log["Facts log<br/>[ast_log.py]"]
  node_llm_log["Prompt log<br/>[llm_log.py]"]
end

node_user(("Source author"))
node_ollama(("Ollama model server"))

node_user -->|"provides source"| node_cli
node_cli -->|"starts analysis"| node_pipeline
node_pipeline -->|"builds facts"| node_ast_builder
node_ast_builder -->|"builds facts"| node_ast_model
node_ast_builder -->|"uses helpers"| node_sql_facts
node_ast_builder -->|"uses helpers"| node_value_sql
node_ast_builder -->|"builds rewrites"| node_rewrites
node_rewrites -->|"reads facts"| node_ast_model
node_pipeline -->|"logs facts"| node_ast_log
node_pipeline -->|"requests suggestions"| node_llm_optimizer
node_llm_optimizer -->|"reads facts"| node_ast_model
node_llm_optimizer -->|"requests generation"| node_ollama_client
node_ollama_client -->|"sends prompts"| node_ollama
node_llm_optimizer -->|"logs prompt"| node_llm_log

click node_cli "https://github.com/ida7jhu/csit998_group10/blob/main/cli.py"
click node_pipeline "https://github.com/ida7jhu/csit998_group10/blob/main/n1_optimizer/pipeline.py"
click node_ast_builder "https://github.com/ida7jhu/csit998_group10/blob/main/n1_optimizer/ast_builder.py"
click node_ast_model "https://github.com/ida7jhu/csit998_group10/blob/main/n1_optimizer/ast_model.py"
click node_sql_facts "https://github.com/ida7jhu/csit998_group10/blob/main/n1_optimizer/sql_facts.py"
click node_value_sql "https://github.com/ida7jhu/csit998_group10/blob/main/n1_optimizer/value_sql.py"
click node_rewrites "https://github.com/ida7jhu/csit998_group10/blob/main/n1_optimizer/rewrites.py"
click node_llm_optimizer "https://github.com/ida7jhu/csit998_group10/blob/main/n1_optimizer/llm_optimizer.py"
click node_ollama_client "https://github.com/ida7jhu/csit998_group10/blob/main/n1_optimizer/ollama_client.py"
click node_ast_log "https://github.com/ida7jhu/csit998_group10/blob/main/n1_optimizer/ast_log.py"
click node_llm_log "https://github.com/ida7jhu/csit998_group10/blob/main/n1_optimizer/llm_log.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,node_pipeline toneBlue
class node_ast_builder,node_ast_model,node_sql_facts,node_value_sql,node_rewrites toneAmber
class node_llm_optimizer,node_ollama_client,node_ollama toneMint
class node_ast_log,node_llm_log toneRose
class node_user toneIndigo
```

## Components

### User interface

- [Command-line interface](https://github.com/ida7jhu/csit998_group10/blob/main/cli.py): `cli.py`
- [Analysis pipeline](https://github.com/ida7jhu/csit998_group10/blob/main/n1_optimizer/pipeline.py): `n1_optimizer/pipeline.py`

### Static analysis

- [Source analyzer](https://github.com/ida7jhu/csit998_group10/blob/main/n1_optimizer/ast_builder.py): `n1_optimizer/ast_builder.py`
- [Procedure facts](https://github.com/ida7jhu/csit998_group10/blob/main/n1_optimizer/ast_model.py): `n1_optimizer/ast_model.py`
- [SQL fact helpers](https://github.com/ida7jhu/csit998_group10/blob/main/n1_optimizer/sql_facts.py): `n1_optimizer/sql_facts.py`
- [Value SQL helpers](https://github.com/ida7jhu/csit998_group10/blob/main/n1_optimizer/value_sql.py): `n1_optimizer/value_sql.py`
- [SQL rewrite builder](https://github.com/ida7jhu/csit998_group10/blob/main/n1_optimizer/rewrites.py): `n1_optimizer/rewrites.py`

### Optimization suggestions

- [Suggestion processor](https://github.com/ida7jhu/csit998_group10/blob/main/n1_optimizer/llm_optimizer.py): `n1_optimizer/llm_optimizer.py`
- [Ollama client](https://github.com/ida7jhu/csit998_group10/blob/main/n1_optimizer/ollama_client.py): `n1_optimizer/ollama_client.py`

### Run logs

- [Facts log](https://github.com/ida7jhu/csit998_group10/blob/main/n1_optimizer/ast_log.py): `n1_optimizer/ast_log.py`
- [Prompt log](https://github.com/ida7jhu/csit998_group10/blob/main/n1_optimizer/llm_log.py): `n1_optimizer/llm_log.py`

### Other components

- **Source author**
- **Ollama model server**

## Connections

- Source author → Command-line interface: provides source (evidence: `README.md`)
- Command-line interface → Analysis pipeline: starts analysis (evidence: `README.md`)
- Analysis pipeline → Source analyzer: builds facts (evidence: `n1_optimizer/pipeline.py`)
- Source analyzer → Procedure facts: builds facts (evidence: `n1_optimizer/ast_builder.py`)
- Source analyzer → SQL fact helpers: uses helpers (evidence: `n1_optimizer/ast_builder.py`)
- Source analyzer → Value SQL helpers: uses helpers (evidence: `n1_optimizer/ast_builder.py`)
- Source analyzer → SQL rewrite builder: builds rewrites (evidence: `n1_optimizer/ast_builder.py`)
- SQL rewrite builder → Procedure facts: reads facts (evidence: `n1_optimizer/rewrites.py`)
- Analysis pipeline → Facts log: logs facts (evidence: `n1_optimizer/pipeline.py`)
- Analysis pipeline → Suggestion processor: requests suggestions (evidence: `n1_optimizer/pipeline.py`)
- Suggestion processor → Procedure facts: reads facts (evidence: `n1_optimizer/llm_optimizer.py`)
- Suggestion processor → Ollama client: requests generation (evidence: `n1_optimizer/llm_optimizer.py`)
- Ollama client → Ollama model server: sends prompts (evidence: `n1_optimizer/ollama_client.py`)
- Suggestion processor → Prompt log: logs prompt (evidence: `n1_optimizer/llm_optimizer.py`)