# iamademar/glamli architecture

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

- Interactive diagram: https://gitdiagram.com/iamademar/glamli
- Repository: https://github.com/iamademar/glamli

## Overview

1. **Repository shape**
   GLAMLI is a monorepo for a guided machine-learning research workflow. The production runtime is split into a React frontend, a Python API/agent backend, a background model-running worker, and two imported WEKA services. The top-level `plans/` folder describes the intended build slices and architecture sequence.

2. **User-facing application**
   `apps/web` is the production frontend: React + TypeScript + Vite. It is organized by workflow stage and feature slice rather than by generic UI layers. The main user journey covers upload, domain understanding, setup, run, explore, and prediction, with assistant chat embedded throughout. State is split across feature hooks and stores for workflow, session, assistant, and UI state.

3. **Backend application boundary**
   `apps/api` is a FastAPI service that owns the application domain and persistence boundary. It exposes REST endpoints for auth, projects, datasets, workflow, events, experiment plans, model runs, predictions, study sessions, and assistant-related actions. It also contains the business services that transform uploaded data, manage study state, and coordinate model/LLM interactions.

4. **Agent and LLM subsystem**
   Inside `apps/api/app/agents`, the backend has a dedicated LLM/agent layer with prompts, role definitions, tone/satisfaction logic, model registry, telemetry, and MCP tool wiring. This is the “single assistant” described in the README: it uses prompt templates per task, calls tools, and records telemetry about assistant behavior and user interactions.

5. **Workflow orchestration**
   The backend has explicit workflow and graph modules (`app/graph`, `app/workflow`) plus a workflow state machine. This suggests the product is not just CRUD; it is a staged, stateful experience where the allowed actions and assistant behavior depend on the participant’s current step. The frontend mirrors this with workflow stores and stage-transition hooks.

6. **Data and experiment pipeline**
   The application domain centers on datasets, domain specifications, column descriptions/groups, EDA checklists, experiment plans, model runs, and predictions. The API services perform normalization, filtering, feature explanation, experiment planning, confidence probing, and result explanation. These pieces form the path from uploaded data to a constrained WEKA experiment and then to prediction/testing.

7. **Background execution**
   `workers/model-runner` is the asynchronous execution boundary. Its job is to run heavier model-experiment work outside the request/response cycle, then feed results back to the API’s persistent state. The presence of recovery services and model-run telemetry indicates the worker must support retries/resume and failure handling, not just one-shot batch jobs.

8. **WEKA integration layer**
   `services/weka-api` is an imported Java/Javalin REST service backed by WEKA 3.9.6. It owns the low-level ML operations: training, evaluation, prediction, transforms, EDA, filtering, clustering, associations, and diagnostics. `services/weka-mcp` is a TypeScript MCP server that wraps that WEKA API and exposes a tool surface for the agent layer. In practice, the Python backend mediates user-facing workflow while the WEKA stack performs the actual ML computation.

9. **Persistence and migrations**
   `apps/api/app/db` plus Alembic migrations show a relational database-backed backend. The migrations define the core study schema: users/auth sessions, projects, datasets and dataset versions, domain specs, experiment plans, model runs, predictions, telemetry, and related recovery/agent tables. The DB is the system of record for the guided study state.

10. **Shared contracts and telemetry**
    `packages/contracts` contains shared API/agent contracts and generated types, bridging Python and TypeScript. `packages/study-events` defines the canonical research telemetry schema in both TS and Python, so frontend, backend, and analysis tooling can emit the same event envelope. This is important because study logging is a first-class product requirement, not an afterthought.

11. **Fixtures, reference UI, and provenance**
    `packages/test-fixtures` provides fixed datasets and model artifacts for deterministic testing. `apps/web-prototype` is a non-production visual reference for the earlier “glamli_v3” UI and should not be treated as runtime code. `docs/weka-service-provenance.md` documents the imported WEKA service lineage, which matters for understanding the external boundary and maintenance ownership.

12. **Operational model**
    The repo is built to run locally via Docker Compose first, with Azure deployment deferred. CI is present in `.github/workflows`, while `compose.yaml` is the main integration point for standing up the database, WEKA services, backend, worker, and eventually the frontend. The architecture is therefore service-oriented but intentionally development-local and study-centric.

Main entry points: [`compose.yaml`](https://github.com/iamademar/glamli/blob/main/compose.yaml) (Compose stack), [`apps/api/app/services`](https://github.com/iamademar/glamli/tree/main/apps/api/app/services) (Domain services), [`apps/api/app/api`](https://github.com/iamademar/glamli/tree/main/apps/api/app/api) (REST routes), [`services/weka-api`](https://github.com/iamademar/glamli/tree/main/services/weka-api) (WEKA API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_web["Frontend"]
  node_web_app["Web app<br/>React+TS UI"]
  node_web_stages["Workflow stages<br/>stage-sliced UI"]
  node_web_assistant["Assistant UI<br/>chat feature"]
  node_web_state["Client state<br/>stores/hooks"]
  node_web_api_client["API client<br/>typed fetch layer"]
end

subgraph group_group_api["Backend"]
  node_api_service["API service<br/>FastAPI backend"]
  node_api_routes["REST routes<br/>endpoint layer"]
  node_api_services["Domain services<br/>business logic"]
  node_api_workflow["Workflow engine<br/>state machine"]
  node_api_graph["Graph logic<br/>workflow graph"]
  node_api_agents["Agent layer<br/>LLM/agent subsystem"]
  node_api_db[("Database<br/>relational persistence")]
  node_api_migrations["Migrations<br/>schema history"]
  node_api_worker["Model worker<br/>async runtime<br/>[worker.py]"]
end

subgraph group_group_ml["ML Services"]
  node_weka_api["WEKA API<br/>Java ML service"]
  node_weka_mcp["WEKA MCP<br/>tool server"]
end

subgraph group_group_shared["Shared"]
  node_shared_contracts["Contracts<br/>shared types"]
  node_shared_events["Study events<br/>telemetry schema"]
  node_shared_fixtures["Fixtures<br/>test assets"]
  node_compose_ops["Compose stack<br/>local orchestration<br/>[compose.yaml]"]
  node_plans_arch["Plans<br/>architecture roadmap"]
end

node_web_app -->|"renders"| node_web_stages
node_web_app -->|"contains"| node_web_assistant
node_web_app -->|"manages"| node_web_state
node_web_app -->|"calls"| node_web_api_client
node_web_stages -->|"reads/writes"| node_api_routes
node_web_assistant -->|"streams"| node_api_agents
node_web_state -->|"emits"| node_shared_events
node_web_api_client -->|"requests"| node_api_routes
node_api_service -->|"exposes"| node_api_routes
node_api_routes -->|"delegates"| node_api_services
node_api_services -->|"persists"| node_api_db
node_api_services -->|"enqueues"| node_api_worker
node_api_services -->|"invokes"| node_weka_api
node_api_worker -->|"runs"| node_weka_api
node_api_worker -->|"updates"| node_api_db
node_api_agents -->|"tools"| node_weka_mcp
node_weka_mcp -->|"proxies"| node_weka_api
node_api_agents -->|"records"| node_api_db
node_api_workflow -->|"defines"| node_api_graph
node_api_routes -->|"enforces"| node_api_workflow
node_api_migrations -->|"migrates"| node_api_db
node_shared_contracts -->|"types"| node_api_service
node_shared_contracts -->|"types"| node_web_api_client
node_shared_events -->|"schemas"| node_api_services
node_shared_events -->|"schemas"| node_web_state
node_shared_fixtures -->|"tests"| node_weka_api
node_compose_ops -->|"orchestrates"| node_api_service
node_compose_ops -->|"orchestrates"| node_api_worker
node_compose_ops -->|"orchestrates"| node_weka_api
node_compose_ops -->|"orchestrates"| node_weka_mcp
node_plans_arch -->|"guides"| node_compose_ops

click node_web_app "https://github.com/iamademar/glamli/tree/main/apps/web"
click node_web_stages "https://github.com/iamademar/glamli/tree/main/apps/web/src/features"
click node_web_assistant "https://github.com/iamademar/glamli/tree/main/apps/web/src/features/assistant"
click node_web_state "https://github.com/iamademar/glamli/tree/main/apps/web/src/store"
click node_web_api_client "https://github.com/iamademar/glamli/tree/main/apps/web/src/api"
click node_api_service "https://github.com/iamademar/glamli/tree/main/apps/api"
click node_api_routes "https://github.com/iamademar/glamli/tree/main/apps/api/app/api"
click node_api_services "https://github.com/iamademar/glamli/tree/main/apps/api/app/services"
click node_api_workflow "https://github.com/iamademar/glamli/tree/main/apps/api/app/workflow"
click node_api_graph "https://github.com/iamademar/glamli/tree/main/apps/api/app/graph"
click node_api_agents "https://github.com/iamademar/glamli/tree/main/apps/api/app/agents"
click node_api_db "https://github.com/iamademar/glamli/tree/main/apps/api/app/db"
click node_api_migrations "https://github.com/iamademar/glamli/tree/main/apps/api/app/alembic/versions"
click node_api_worker "https://github.com/iamademar/glamli/blob/main/apps/api/app/worker.py"
click node_weka_api "https://github.com/iamademar/glamli/tree/main/services/weka-api"
click node_weka_mcp "https://github.com/iamademar/glamli/tree/main/services/weka-mcp"
click node_shared_contracts "https://github.com/iamademar/glamli/tree/main/packages/contracts"
click node_shared_events "https://github.com/iamademar/glamli/tree/main/packages/study-events"
click node_shared_fixtures "https://github.com/iamademar/glamli/tree/main/packages/test-fixtures"
click node_compose_ops "https://github.com/iamademar/glamli/blob/main/compose.yaml"
click node_plans_arch "https://github.com/iamademar/glamli/tree/main/plans"

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_web_app,node_web_stages,node_web_assistant,node_web_state,node_web_api_client toneBlue
class node_api_service,node_api_routes,node_api_services,node_api_workflow,node_api_graph,node_api_agents,node_api_db,node_api_migrations,node_api_worker toneAmber
class node_weka_api,node_weka_mcp toneMint
class node_shared_contracts,node_shared_events,node_shared_fixtures,node_compose_ops,node_plans_arch toneRose
```

## Components

### Frontend

React workflow UI and client-side state

- [Web app](https://github.com/iamademar/glamli/tree/main/apps/web): React+TS UI · Production frontend for the guided research workflow · `apps/web`
- [Workflow stages](https://github.com/iamademar/glamli/tree/main/apps/web/src/features): stage-sliced UI · Upload, domain, setup, run, explore, and predict screens · `apps/web/src/features`
- [Assistant UI](https://github.com/iamademar/glamli/tree/main/apps/web/src/features/assistant): chat feature · Embedded chat, checklist prompts, and stage-aware replies · `apps/web/src/features/assistant`
- [Client state](https://github.com/iamademar/glamli/tree/main/apps/web/src/store): stores/hooks · Workflow, session, assistant, and UI state management · `apps/web/src/store`
- [API client](https://github.com/iamademar/glamli/tree/main/apps/web/src/api): typed fetch layer · Client wrappers and query keys for backend calls · `apps/web/src/api`

### Backend

FastAPI domain service and orchestration

- [API service](https://github.com/iamademar/glamli/tree/main/apps/api): FastAPI backend · Owns application domain, persistence, and public REST surface · `apps/api`
- [REST routes](https://github.com/iamademar/glamli/tree/main/apps/api/app/api): endpoint layer · Auth, projects, datasets, workflow, runs, predictions, and telemetry endpoints · `apps/api/app/api`
- [Domain services](https://github.com/iamademar/glamli/tree/main/apps/api/app/services): business logic · Data normalization, study state, planning, explanations, and run coordination · `apps/api/app/services`
- [Workflow engine](https://github.com/iamademar/glamli/tree/main/apps/api/app/workflow): state machine · Stage definitions and routing for allowed participant actions · `apps/api/app/workflow`
- [Graph logic](https://github.com/iamademar/glamli/tree/main/apps/api/app/graph): workflow graph · Workflow routing and state representation for the staged experience · `apps/api/app/graph`
- [Agent layer](https://github.com/iamademar/glamli/tree/main/apps/api/app/agents): LLM/agent subsystem · Prompting, tool wiring, telemetry, roles, tone, and satisfaction logic · `apps/api/app/agents`
- [Database](https://github.com/iamademar/glamli/tree/main/apps/api/app/db): relational persistence · System of record for studies, users, datasets, runs, predictions, and telemetry · `apps/api/app/db`
- [Migrations](https://github.com/iamademar/glamli/tree/main/apps/api/app/alembic/versions): schema history · Alembic revisions defining the core study schema · `apps/api/app/alembic/versions`
- [Model worker](https://github.com/iamademar/glamli/blob/main/apps/api/app/worker.py): async runtime · Background execution boundary for heavier model-run work and recovery · `apps/api/app/worker.py`

### ML Services

Imported WEKA runtime and MCP bridge

- [WEKA API](https://github.com/iamademar/glamli/tree/main/services/weka-api): Java ML service · Imported service implementing training, evaluation, prediction, transforms, and EDA · `services/weka-api`
- [WEKA MCP](https://github.com/iamademar/glamli/tree/main/services/weka-mcp): tool server · TypeScript MCP layer exposing WEKA tools to the agent subsystem · `services/weka-mcp`

### Shared

Contracts, telemetry, fixtures, and repo-level ops

- [Contracts](https://github.com/iamademar/glamli/tree/main/packages/contracts): shared types · Cross-runtime API and agent contracts for Python and TypeScript · `packages/contracts`
- [Study events](https://github.com/iamademar/glamli/tree/main/packages/study-events): telemetry schema · Canonical event envelope shared by frontend, backend, and analysis tooling · `packages/study-events`
- [Fixtures](https://github.com/iamademar/glamli/tree/main/packages/test-fixtures): test assets · Deterministic datasets and model artifacts for repeatable tests · `packages/test-fixtures`
- [Compose stack](https://github.com/iamademar/glamli/blob/main/compose.yaml): local orchestration · Main local integration entrypoint for database and services · `compose.yaml`
- [Plans](https://github.com/iamademar/glamli/tree/main/plans): architecture roadmap · Top-level build slices and intended implementation sequence · `plans`

## Connections

- Web app → Workflow stages: renders · The app is organized around workflow-stage screens and feature slices
- Web app → Assistant UI: contains · Assistant chat is embedded throughout the user journey
- Web app → Client state: manages · Client state is split across dedicated stores and hooks
- Web app → API client: calls · Frontend data access goes through typed API wrappers
- Workflow stages → REST routes: reads/writes · Stage UI depends on backend workflow and domain endpoints
- Assistant UI → Agent layer: streams · Chat UI is backed by the assistant and prompt subsystem
- Client state → Study events: emits · Client telemetry uses the shared study-event envelope
- API client → REST routes: requests · Client API module is the frontend boundary to the backend
- API service → REST routes: exposes · FastAPI mounts the public REST surface
- REST routes → Domain services: delegates · Routes hand off to domain services for execution
- Domain services → Database: persists · Domain state and study artifacts are stored in the relational database
- Domain services → Model worker: enqueues · Heavy or recoverable work is pushed to the background worker
- Domain services → WEKA API: invokes · Core ML computation is performed by the WEKA service
- Model worker → WEKA API: runs · Worker executes model-run jobs through the WEKA boundary
- Model worker → Database: updates · Worker feeds results and recovery state back into persistence
- Agent layer → WEKA MCP: tools · Agent tool usage is mediated through the MCP wrapper
- WEKA MCP → WEKA API: proxies · MCP server forwards tool calls to the Java WEKA REST service
- Agent layer → Database: records · Assistant telemetry and outputs are stored for the study
- Workflow engine → Graph logic: defines · Workflow stages and graph routing describe allowed transitions
- REST routes → Workflow engine: enforces · Workflow endpoints respect the staged participant state
- Migrations → Database: migrates · Alembic revisions define the database schema and evolution
- Contracts → API service: types · Shared contracts bridge Python backend models and APIs
- Contracts → API client: types · Shared contracts also bridge frontend request/response types
- Study events → Domain services: schemas · Backend emits canonical study telemetry through shared schemas
- Study events → Client state: schemas · Frontend telemetry follows the same event definitions
- Fixtures → WEKA API: tests · Reference datasets and models support deterministic ML tests
- Compose stack → API service: orchestrates · Compose is the local runtime entrypoint for backend services
- Compose stack → Model worker: orchestrates · Compose also brings up the background worker
- Compose stack → WEKA API: orchestrates · Compose includes the imported WEKA API service
- Compose stack → WEKA MCP: orchestrates · Compose includes the MCP bridge service
- Plans → Compose stack: guides · Implementation plans describe the intended local stack and build slices
