# javatcoding1/devops-autoheal architecture

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

- Interactive diagram: https://gitdiagram.com/javatcoding1/devops-autoheal
- Repository: https://github.com/javatcoding1/devops-autoheal

## Overview

1. This repository is centered on a single simulated DevOps/SRE environment, exposed through three entry points: a FastAPI server, a Streamlit dashboard, and a CLI inference agent. The shared purpose is to let an AI agent observe system state, take corrective actions, and score its recovery performance.

2. The core simulation logic appears to live in `server/my_env_environment.py`, with shared data schemas in `models.py`. This is the main boundary of the repo: it defines the environment state, hidden failure modes, allowed actions, and episode transitions that the rest of the project consumes.

3. The server layer is in `server/app.py`, which is the primary runtime interface for the environment. Based on the README, it likely exposes OpenEnv-compatible endpoints such as reset/step/auto-run and serves both API access and the spec/docs surfaces used for deployment.

4. `streamlit_app.py` is the interactive visualization layer. It sits on top of the same environment semantics and is meant for humans to inspect current metrics, service health, and episode progression without using the agent or API directly.

5. `inference.py` is the autonomous agent runner. It consumes observations from the environment, applies an LLM-backed reasoning protocol, and emits actions. The README indicates it includes heuristic fallbacks, so the control flow is “LLM first, deterministic safety rules second.”

6. `client.py` is the likely integration helper for interacting with the server from local scripts or other tooling. Architecturally, it sits between user-side code and the FastAPI environment API, keeping the transport details out of the agent or UI logic.

7. The project uses a dual-state simulation model: observable metrics such as CPU, memory, latency, and service status, plus hidden root causes such as memory leaks, database locks, or scaling bottlenecks. That distinction is important for the architecture diagram because the agent cannot infer the true cause from metrics alone; it must sometimes query logs.

8. The environment behavior is event-driven and stateful rather than stateless request/response. Actions like restart, scale-up, database optimization, cache clearing, and log inspection mutate the simulated system, and those mutations feed back into later observations and rewards.

9. There is no evidence of a backing database or external state store; the simulation is self-contained in process. Persistence boundaries are therefore mostly deployment/runtime boundaries: API server process, Streamlit UI process, and inference CLI process all talk to the same environment logic, not to an external datastore.

10. Deployment is container-oriented. `Dockerfile`, `server/start.sh`, `openenv.yaml`, and the Python dependency files (`requirements.txt`, `server/requirements.txt`, `pyproject.toml`, `uv.lock`) define packaging and runtime behavior for Hugging Face Spaces/OpenEnv-style deployment, with the server expected on port 8000 and the UI on Streamlit’s default port.

11. The repo also includes support files for reproducible Python execution and runtime isolation (`__init__.py`, `server/__init__.py`, `.gitignore`). These are not architectural subsystems themselves, but they reinforce that the project is organized as a small service bundle around one simulation core rather than a multi-service backend.

12. For an architecture diagram, the cleanest structure is: environment core at the center; FastAPI server, Streamlit UI, and inference agent as three consumers; shared models/schemas as the contract layer; and Docker/OpenEnv packaging as the deployment wrapper around all of it.

Main entry points: [`server/my_env_environment.py`](https://github.com/javatcoding1/devops-autoheal/blob/main/server/my_env_environment.py) (Env Kernel), [`server/app.py`](https://github.com/javatcoding1/devops-autoheal/blob/main/server/app.py) (FastAPI Server), [`streamlit_app.py`](https://github.com/javatcoding1/devops-autoheal/blob/main/streamlit_app.py) (Streamlit UI), [`inference.py`](https://github.com/javatcoding1/devops-autoheal/blob/main/inference.py) (Inference CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Simulation Core"]
  node_env_kernel["Env Kernel<br/>simulator"]
  node_models["Schemas<br/>contracts<br/>[models.py]"]
  node_observable_metrics(("Metrics<br/>observability"))
  node_hidden_faults{{"Hidden Faults<br/>failure-state"}}
  node_action_effects["Actions<br/>control-plane"]
  node_episode_scoring(("Scoring<br/>reward"))
end

subgraph group_interfaces["Runtime Interfaces"]
  node_api_server["FastAPI Server<br/>api-runtime<br/>[app.py]"]
  node_ui_dashboard["Streamlit UI<br/>dashboard<br/>[streamlit_app.py]"]
  node_cli_agent["Inference CLI<br/>agent-runtime<br/>[inference.py]"]
  node_client_helper["Client Helper<br/>integration<br/>[client.py]"]
  node_api_contract["API Contract<br/>schema-boundary"]
end

subgraph group_deployment["Deployment"]
  node_container_image["Container Image<br/>packaging"]
  node_openenv_spec["OpenEnv Spec<br/>deployment-spec<br/>[openenv.yaml]"]
  node_server_entrypoint["Server Start<br/>startup-script<br/>[start.sh]"]
  node_python_deps["Python Deps<br/>runtime-config<br/>[pyproject.toml]"]
end

node_api_server -->|"drives"| node_env_kernel
node_ui_dashboard -->|"reads"| node_env_kernel
node_cli_agent -->|"uses"| node_client_helper
node_client_helper -->|"calls"| node_api_server
node_env_kernel -->|"encodes"| node_models
node_api_server -->|"serializes"| node_api_contract
node_ui_dashboard -->|"consumes"| node_api_contract
node_cli_agent -->|"consumes"| node_api_contract
node_env_kernel -->|"produces"| node_observable_metrics
node_env_kernel -->|"contains"| node_hidden_faults
node_env_kernel -->|"applies"| node_action_effects
node_env_kernel -->|"evaluates"| node_episode_scoring
node_api_server -->|"runs in"| node_container_image
node_ui_dashboard -->|"runs in"| node_container_image
node_server_entrypoint -->|"launches"| node_api_server
node_openenv_spec -->|"configures"| node_api_server
node_python_deps -->|"supports"| node_api_server
node_python_deps -->|"supports"| node_cli_agent

click node_env_kernel "https://github.com/javatcoding1/devops-autoheal/blob/main/server/my_env_environment.py"
click node_models "https://github.com/javatcoding1/devops-autoheal/blob/main/models.py"
click node_api_server "https://github.com/javatcoding1/devops-autoheal/blob/main/server/app.py"
click node_ui_dashboard "https://github.com/javatcoding1/devops-autoheal/blob/main/streamlit_app.py"
click node_cli_agent "https://github.com/javatcoding1/devops-autoheal/blob/main/inference.py"
click node_client_helper "https://github.com/javatcoding1/devops-autoheal/blob/main/client.py"
click node_container_image "https://github.com/javatcoding1/devops-autoheal/tree/main/Dockerfile"
click node_openenv_spec "https://github.com/javatcoding1/devops-autoheal/blob/main/openenv.yaml"
click node_server_entrypoint "https://github.com/javatcoding1/devops-autoheal/blob/main/server/start.sh"
click node_python_deps "https://github.com/javatcoding1/devops-autoheal/blob/main/pyproject.toml"

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_env_kernel,node_models,node_observable_metrics,node_hidden_faults,node_action_effects,node_episode_scoring toneBlue
class node_api_server,node_ui_dashboard,node_cli_agent,node_client_helper,node_api_contract toneAmber
class node_container_image,node_openenv_spec,node_server_entrypoint,node_python_deps toneMint
```

## Components

### Simulation Core

Self-contained environment state machine, schemas, and reward logic.

- [Env Kernel](https://github.com/javatcoding1/devops-autoheal/blob/main/server/my_env_environment.py): simulator · Main episode engine that applies actions, updates state, and advances the simulation. · `server/my_env_environment.py`
- [Schemas](https://github.com/javatcoding1/devops-autoheal/blob/main/models.py): contracts · Shared data models and structured state definitions used across the repo. · `models.py`
- **Metrics**: observability · Exposed system signals such as CPU, memory, latency, and service status.
- **Hidden Faults**: failure-state · Latent root causes like leaks, locks, and bottlenecks that are not directly visible.
- **Actions**: control-plane · Allowed corrective operations such as restart, scale, optimize, clear cache, and inspect logs.
- **Scoring**: reward · Episode progression, recovery assessment, and outcome scoring.

### Runtime Interfaces

Human, agent, and API entry points that drive the same environment.

- [FastAPI Server](https://github.com/javatcoding1/devops-autoheal/blob/main/server/app.py): api-runtime · Primary HTTP runtime exposing the environment and OpenEnv-compatible endpoints. · `server/app.py`
- [Streamlit UI](https://github.com/javatcoding1/devops-autoheal/blob/main/streamlit_app.py): dashboard · Interactive human-facing view for metrics, health, and episode progress. · `streamlit_app.py`
- [Inference CLI](https://github.com/javatcoding1/devops-autoheal/blob/main/inference.py): agent-runtime · LLM-backed autonomous runner with heuristic fallback logic. · `inference.py`
- [Client Helper](https://github.com/javatcoding1/devops-autoheal/blob/main/client.py): integration · Local transport wrapper for calling the environment API from scripts or tools. · `client.py`
- **API Contract**: schema-boundary · Request and response structure shared between the server, UI, and agent.

### Deployment

Packaging and runtime entrypoints for container and OpenEnv-style execution.

- [Container Image](https://github.com/javatcoding1/devops-autoheal/tree/main/Dockerfile): packaging · Docker-based runtime bundle for deployment. · `Dockerfile`
- [OpenEnv Spec](https://github.com/javatcoding1/devops-autoheal/blob/main/openenv.yaml): deployment-spec · Environment metadata and deployment configuration for OpenEnv-style hosting. · `openenv.yaml`
- [Server Start](https://github.com/javatcoding1/devops-autoheal/blob/main/server/start.sh): startup-script · Shell entrypoint used to launch the API server in deployment. · `server/start.sh`
- [Python Deps](https://github.com/javatcoding1/devops-autoheal/blob/main/pyproject.toml): runtime-config · Python dependency and environment management for reproducible execution. · `pyproject.toml`

## Connections

- FastAPI Server → Env Kernel: drives · HTTP requests trigger environment reset, step, and auto-run behavior.
- Streamlit UI → Env Kernel: reads · Dashboard renders live state and episode progress from the same simulation.
- Inference CLI → Client Helper: uses · The autonomous runner relies on the client layer for API interaction.
- Client Helper → FastAPI Server: calls · Local scripts and tooling go through the API wrapper to reach the server.
- Env Kernel → Schemas: encodes · The environment state and transitions are defined by shared schemas.
- FastAPI Server → API Contract: serializes · The server exposes the structured API contract to consumers.
- Streamlit UI → API Contract: consumes · The UI uses the same structured observation and action shapes.
- Inference CLI → API Contract: consumes · The agent reasons over the same observation and action contract.
- Env Kernel → Metrics: produces · The simulator emits observable health and performance signals.
- Env Kernel → Hidden Faults: contains · Latent failure modes live inside the simulation but are not directly exposed.
- Env Kernel → Actions: applies · Corrective actions mutate the simulated system state.
- Env Kernel → Scoring: evaluates · State transitions feed recovery progress and reward calculation.
- FastAPI Server → Container Image: runs in · The HTTP service is packaged for containerized deployment.
- Streamlit UI → Container Image: runs in · The dashboard is also part of the packaged runtime bundle.
- Server Start → FastAPI Server: launches · Startup script boots the server process in deployment.
- OpenEnv Spec → FastAPI Server: configures · Deployment metadata points to the server runtime and ports.
- Python Deps → FastAPI Server: supports · Python environment definitions support the server and shared code.
- Python Deps → Inference CLI: supports · Dependency management also underpins the inference runner.
