# guruvaidev/avaloka architecture

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

- Interactive diagram: https://gitdiagram.com/guruvaidev/avaloka
- Repository: https://github.com/guruvaidev/avaloka

## Overview

Avaloka turns a natural-language goal and dataset into a checked analysis, reproducible artifacts, and optionally a trained and served model. Users can enter through the CLI or the web/API platform; the documented analysis path profiles data, plans and validates code, executes it, then reports findings with lineage. Training and deployment, Auto Insights, collaboration, scheduled and distributed runs, and data connectors are major product branches. The README documents the workflow; source excerpts and the index give only partial implementation evidence, so unverified internal links are omitted.

Main entry points: [`avaloka/cli.py`](https://github.com/guruvaidev/avaloka/blob/main/avaloka/cli.py) (Avaloka CLI), [`app/api/server.py`](https://github.com/guruvaidev/avaloka/blob/main/app/api/server.py) (Web and API), [`app/agents/execution_agent.py`](https://github.com/guruvaidev/avaloka/blob/main/app/agents/execution_agent.py) (Analysis execution), [`app/agents/result_narrator.py`](https://github.com/guruvaidev/avaloka/blob/main/app/agents/result_narrator.py) (Results and lineage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["Avaloka CLI<br/>[cli.py]"]
  node_webapi["Web and API<br/>[server.py]"]
  node_webui["Web dashboard"]
  node_service["Analysis service<br/>[service.py]"]
end

subgraph group_analysis["Analysis workflow"]
  node_planner["Goal planner<br/>[planner.py]"]
  node_profiling["Data profiling<br/>[profiling_agent.py]"]
  node_preparation["Data preparation"]
  node_coder["Analysis coding<br/>[coder.py]"]
  node_validator["Code validation<br/>[validator.py]"]
  node_executor["Analysis execution<br/>[execution_agent.py]"]
  node_visualizer["Visualization"]
  node_report["Results and lineage<br/>[result_narrator.py]"]
end

subgraph group_data["Data and artifacts"]
  node_connectors["File connectors<br/>[handler.py]"]
  node_sampling["Data sampling"]
  node_artifacts["Run artifacts<br/>[artifacts.py]"]
end

subgraph group_models["Model lifecycle"]
  node_training["Model training<br/>[agent.py]"]
  node_inference["Model inference<br/>[inference.py]"]
  node_deployment["Cloud deployment"]
end

subgraph group_platform["Platform services"]
  node_storage[("Object storage<br/>[storage.py]")]
  node_ray["Ray execution<br/>[ray_manager.py]"]
  node_schedule["Scheduled runs<br/>[scheduler.py]"]
  node_memory[("Layered memory<br/>[memory_runtime.py]")]
end

node_user(("Analyst"))

node_user -->|"asks goal"| node_cli
node_user -.->|"submits analysis"| node_webapi
node_webui -.->|"uses platform"| node_webapi
node_cli -->|"profiles data"| node_profiling
node_cli -->|"plans analysis"| node_planner
node_cli -->|"writes code"| node_coder
node_cli -->|"validates code"| node_validator
node_cli -->|"runs analysis"| node_executor
node_cli -->|"reports findings"| node_report
node_connectors -.->|"provides rows"| node_sampling
node_executor -.->|"records outputs"| node_artifacts
node_artifacts -.->|"persists artifacts"| node_storage
node_cli -->|"trains model"| node_training
node_training -.->|"enables inference"| node_inference
node_inference -.->|"deploys service"| node_deployment
node_cli -->|"distributes runs"| node_ray
node_webapi -.->|"schedules runs"| node_schedule
node_report -.->|"records results"| node_memory

click node_cli "https://github.com/guruvaidev/avaloka/blob/main/avaloka/cli.py"
click node_webapi "https://github.com/guruvaidev/avaloka/blob/main/app/api/server.py"
click node_webui "https://github.com/guruvaidev/avaloka/tree/main/ui/src/components/dashboard"
click node_service "https://github.com/guruvaidev/avaloka/blob/main/app/interfaces/service.py"
click node_planner "https://github.com/guruvaidev/avaloka/blob/main/app/agents/planner.py"
click node_profiling "https://github.com/guruvaidev/avaloka/blob/main/app/agents/profiling_agent.py"
click node_preparation "https://github.com/guruvaidev/avaloka/blob/main/app/agents/preparation_pipeline.py"
click node_coder "https://github.com/guruvaidev/avaloka/blob/main/app/agents/coder.py"
click node_validator "https://github.com/guruvaidev/avaloka/blob/main/app/agents/validator.py"
click node_executor "https://github.com/guruvaidev/avaloka/blob/main/app/agents/execution_agent.py"
click node_visualizer "https://github.com/guruvaidev/avaloka/blob/main/app/agents/visualization_agent.py"
click node_report "https://github.com/guruvaidev/avaloka/blob/main/app/agents/result_narrator.py"
click node_connectors "https://github.com/guruvaidev/avaloka/blob/main/file_handler/handler.py"
click node_sampling "https://github.com/guruvaidev/avaloka/blob/main/app/agents/sampling_agent_daft.py"
click node_artifacts "https://github.com/guruvaidev/avaloka/blob/main/app/interfaces/artifacts.py"
click node_storage "https://github.com/guruvaidev/avaloka/blob/main/app/core/storage.py"
click node_training "https://github.com/guruvaidev/avaloka/blob/main/app/agents/mta_v2/agent.py"
click node_inference "https://github.com/guruvaidev/avaloka/blob/main/app/agents/mta_v2/inference.py"
click node_deployment "https://github.com/guruvaidev/avaloka/blob/main/app/agents/mta_v2/inference_service_manager.py"
click node_ray "https://github.com/guruvaidev/avaloka/blob/main/app/infra/ray_manager.py"
click node_schedule "https://github.com/guruvaidev/avaloka/blob/main/app/agents/scheduler.py"
click node_memory "https://github.com/guruvaidev/avaloka/blob/main/app/services/memory_runtime.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_webapi,node_webui,node_service toneBlue
class node_planner,node_profiling,node_preparation,node_coder,node_validator,node_executor,node_visualizer,node_report toneAmber
class node_connectors,node_sampling,node_artifacts toneMint
class node_training,node_inference,node_deployment toneRose
class node_storage,node_ray,node_schedule,node_memory,node_user toneIndigo
```

## Components

### User interfaces

- [Avaloka CLI](https://github.com/guruvaidev/avaloka/blob/main/avaloka/cli.py): `avaloka/cli.py`
- [Web and API](https://github.com/guruvaidev/avaloka/blob/main/app/api/server.py): `app/api/server.py`
- [Web dashboard](https://github.com/guruvaidev/avaloka/tree/main/ui/src/components/dashboard): `ui/src/components/dashboard`
- [Analysis service](https://github.com/guruvaidev/avaloka/blob/main/app/interfaces/service.py): `app/interfaces/service.py`

### Analysis workflow

- [Goal planner](https://github.com/guruvaidev/avaloka/blob/main/app/agents/planner.py): `app/agents/planner.py`
- [Data profiling](https://github.com/guruvaidev/avaloka/blob/main/app/agents/profiling_agent.py): `app/agents/profiling_agent.py`
- [Data preparation](https://github.com/guruvaidev/avaloka/blob/main/app/agents/preparation_pipeline.py): `app/agents/preparation_pipeline.py`
- [Analysis coding](https://github.com/guruvaidev/avaloka/blob/main/app/agents/coder.py): `app/agents/coder.py`
- [Code validation](https://github.com/guruvaidev/avaloka/blob/main/app/agents/validator.py): `app/agents/validator.py`
- [Analysis execution](https://github.com/guruvaidev/avaloka/blob/main/app/agents/execution_agent.py): `app/agents/execution_agent.py`
- [Visualization](https://github.com/guruvaidev/avaloka/blob/main/app/agents/visualization_agent.py): `app/agents/visualization_agent.py`
- [Results and lineage](https://github.com/guruvaidev/avaloka/blob/main/app/agents/result_narrator.py): `app/agents/result_narrator.py`

### Data and artifacts

- [File connectors](https://github.com/guruvaidev/avaloka/blob/main/file_handler/handler.py): `file_handler/handler.py`
- [Data sampling](https://github.com/guruvaidev/avaloka/blob/main/app/agents/sampling_agent_daft.py): `app/agents/sampling_agent_daft.py`
- [Run artifacts](https://github.com/guruvaidev/avaloka/blob/main/app/interfaces/artifacts.py): `app/interfaces/artifacts.py`

### Model lifecycle

- [Model training](https://github.com/guruvaidev/avaloka/blob/main/app/agents/mta_v2/agent.py): `app/agents/mta_v2/agent.py`
- [Model inference](https://github.com/guruvaidev/avaloka/blob/main/app/agents/mta_v2/inference.py): `app/agents/mta_v2/inference.py`
- [Cloud deployment](https://github.com/guruvaidev/avaloka/blob/main/app/agents/mta_v2/inference_service_manager.py): `app/agents/mta_v2/inference_service_manager.py`

### Platform services

- [Object storage](https://github.com/guruvaidev/avaloka/blob/main/app/core/storage.py): `app/core/storage.py`
- [Ray execution](https://github.com/guruvaidev/avaloka/blob/main/app/infra/ray_manager.py): `app/infra/ray_manager.py`
- [Scheduled runs](https://github.com/guruvaidev/avaloka/blob/main/app/agents/scheduler.py): `app/agents/scheduler.py`
- [Layered memory](https://github.com/guruvaidev/avaloka/blob/main/app/services/memory_runtime.py): `app/services/memory_runtime.py`

### Other components

- **Analyst**

## Connections

- Analyst → Avaloka CLI: asks goal (evidence: `README.md`)
- Analyst → Web and API: submits analysis
- Web dashboard → Web and API: uses platform
- Avaloka CLI → Data profiling: profiles data (evidence: `README.md`)
- Avaloka CLI → Goal planner: plans analysis (evidence: `README.md`)
- Avaloka CLI → Analysis coding: writes code (evidence: `README.md`)
- Avaloka CLI → Code validation: validates code (evidence: `README.md`)
- Avaloka CLI → Analysis execution: runs analysis (evidence: `README.md`)
- Avaloka CLI → Results and lineage: reports findings (evidence: `README.md`)
- File connectors → Data sampling: provides rows
- Analysis execution → Run artifacts: records outputs
- Run artifacts → Object storage: persists artifacts
- Avaloka CLI → Model training: trains model (evidence: `README.md`)
- Model training → Model inference: enables inference
- Model inference → Cloud deployment: deploys service (evidence: `app/agents/mta_v2/inference_service_manager.py`)
- Avaloka CLI → Ray execution: distributes runs (evidence: `README.md`)
- Web and API → Scheduled runs: schedules runs
- Results and lineage → Layered memory: records results