# 3mper0rr/cosmicengineai architecture

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

- Interactive diagram: https://gitdiagram.com/3mper0rr/cosmicengineai
- Repository: https://github.com/3mper0rr/cosmicengineai

## Overview

1. **High-level shape**
   Cosmic Engine is a mixed C/C++ runtime with a small core and pluggable execution paths. The main binary appears to be a terminal-oriented AI runtime that can drive text generation and, separately, an image-generation pipeline. The repo is split into a low-level runtime layer, provider adapters, telemetry/stream inspection, and optional Python tooling.

2. **Primary entry point**
   `src/main.c` is the likely CLI entry into the runtime. From there, requests flow into the engine/router layer rather than directly into a provider. The README’s usage suggests the binary accepts a mode such as `llm prompt`, which then selects the relevant backend path.

3. **Core runtime / orchestration layer**
   `src/engine.c`, `src/engine.h`, and `src/engine_router.c` look like the central dispatch layer. This is where model requests are normalized, routed, and handed off to the correct backend or provider implementation. `src/orchestrator/orchestrator.cpp` plus its headers suggest a higher-level coordination layer, likely responsible for composing backend selection, request lifecycle, and provider capability decisions.

4. **Backend abstraction**
   `src/backend.cpp/.h` and `src/http.c/.h` form the abstraction boundary between the engine and transport/provider-specific execution. This is likely where the runtime isolates generic request handling from the details of HTTP calls, streaming, and backend-specific response handling. The repository’s README explicitly calls out a “HTTP backend abstraction layer.”

5. **Provider implementation boundary**
   The concrete text provider currently present is Groq. `src/providers/groq/stream.c/.h` is the provider-specific streaming adapter, likely responsible for reading Server-Sent Events, parsing chunks, and extracting deltas from the Groq API response. This is the main place where provider-specific wire format handling lives.

6. **Streaming and observability**
   Streaming is a first-class subsystem, not just an output detail. The README highlights raw chunk inspection, delta extraction, SSE handling, and TTFB measurement. That functionality appears to be split across `src/telemetry.cpp/.hpp` and `src/telemetry/telemetry.c/.h`, with `src/probe.cpp/.hpp` likely measuring transport timing or chunk arrival behavior. The architecture therefore includes an observability lane alongside the request lane.

7. **Bridging C and C++**
   `src/bridge.cpp/.hpp` likely provides glue between the C runtime pieces and the C++ orchestration/telemetry components. This matters architecturally because the repo is not a single-language codebase; the bridge probably keeps the C entry/runtime layers interoperable with C++ orchestration and higher-level utilities.

8. **Image-generation path**
   Image generation is separate from the LLM text path. `src/img_backend.c/.h` appears to encapsulate image-provider access, and the README says HuggingFace Inference API is the current image provider. The image path is also supported by optional Python tooling in `tools/run_img.py`, indicating that image workflows may be partially externalized from the C/C++ core.

9. **Configuration and runtime dependencies**
   `src/config.h` likely centralizes compile-time or environment-driven configuration, including API keys and provider toggles. The runtime depends materially on `libcurl` for outbound HTTP. The README shows environment-based configuration for `GROQ_API_KEY` and `HF_TOKEN`, so secrets and provider selection are runtime inputs rather than baked into the binary.

10. **External services**
    The main external dependency today is the Groq API for streaming LLM inference. HuggingFace Inference API is used for image generation. Ollama is mentioned as planned/partial, and OpenRouter/Gemini are listed as future or experimental providers, so the architecture is explicitly designed to expand across multiple inference vendors.

11. **Execution flow for text generation**
    A typical text request likely flows: CLI entry point → engine/router → backend abstraction → Groq provider stream handler → HTTP/SSE transport → telemetry/probe capture → terminal output. The important architectural point is that response streaming and measurement happen during transport, not only after completion.

12. **Execution flow for image generation**
    The image path is more loosely coupled: the core runtime or a helper backend invokes the image backend, while the Python tooling can stand up the environment and run the HuggingFace-based generation script. This suggests image generation is adjacent to, but not fully embedded in, the C/C++ runtime core.

13. **Tooling and developer workflow**
    `makefile` builds the native runtime; `tools/menu.sh` and `tools/ollama_cloud.sh` appear to support setup or provider workflows; `tools/run_img.py` supports the Python image pipeline. So the repo has two operational modes: a compiled native runtime for text/streaming, and a Python-assisted path for image generation.

14. **Notable structural constraint**
    The repository contains several `* copia.*` files, which look like backups or alternate snapshots of core modules. For architecture diagrams, the stable conceptual modules are the non-`copia` files: main/runtime, engine/router, backend/HTTP, provider streams, telemetry/probe, orchestrator, and image backend.

Main entry points: [`src/backend.cpp`](https://github.com/3mper0rr/cosmicengineai/blob/main/src/backend.cpp) (Backend), [`src/orchestrator/orchestrator.cpp`](https://github.com/3mper0rr/cosmicengineai/blob/main/src/orchestrator/orchestrator.cpp) (Orchestrator), [`src/main.c`](https://github.com/3mper0rr/cosmicengineai/blob/main/src/main.c) (Main), [`src/config.h`](https://github.com/3mper0rr/cosmicengineai/blob/main/src/config.h) (Config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Core runtime"]
  node_main["Main<br/>CLI entry<br/>[main.c]"]
  node_engine["Engine<br/>request core<br/>[engine.c]"]
  node_router["Router<br/>dispatch<br/>[engine_router.c]"]
  node_orchestrator["Orchestrator<br/>coordination<br/>[orchestrator.cpp]"]
  node_backend["Backend<br/>abstraction<br/>[backend.cpp]"]
  node_http["HTTP<br/>transport<br/>[http.c]"]
  node_bridge["Bridge<br/>c-c++ glue<br/>[bridge.cpp]"]
  node_config["Config<br/>settings<br/>[config.h]"]
end

subgraph group_observability["Observability"]
  node_telemetry["Telemetry<br/>stream metrics<br/>[telemetry.cpp]"]
  node_probe["Probe<br/>[probe.cpp]"]
  node_telemetry_c["Telemetry C<br/>runtime metrics<br/>[telemetry.c]"]
end

subgraph group_providers["Providers"]
  node_groq_stream["Groq stream<br/>provider adapter<br/>[stream.c]"]
end

subgraph group_image["Image path"]
  node_img_backend["Image backend<br/>image provider<br/>[img_backend.c]"]
end

subgraph group_tooling["Tooling"]
  node_run_img["Run image<br/>python tool<br/>[run_img.py]"]
  node_menu["Menu<br/>shell tool<br/>[menu.sh]"]
  node_ollama_cloud["Ollama cloud<br/>shell tool<br/>[ollama_cloud.sh]"]
end

node_main -->|"starts"| node_engine
node_engine -->|"routes"| node_router
node_router -->|"coordinates"| node_orchestrator
node_orchestrator -->|"selects"| node_backend
node_backend -->|"uses"| node_http
node_http -->|"streams"| node_groq_stream
node_groq_stream -->|"reports"| node_telemetry
node_telemetry -->|"measures"| node_probe
node_telemetry -->|"bridges"| node_telemetry_c
node_main -.->|"links"| node_bridge
node_bridge -.->|"glues"| node_orchestrator
node_config -.->|"configures"| node_engine
node_config -.->|"configures"| node_backend
node_config -.->|"secrets"| node_groq_stream
node_backend -->|"image path"| node_img_backend
node_run_img -->|"drives"| node_img_backend
node_menu -.->|"assists"| node_run_img
node_ollama_cloud -.->|"supports"| node_orchestrator
node_main -.->|"optional mode"| node_img_backend

click node_main "https://github.com/3mper0rr/cosmicengineai/blob/main/src/main.c"
click node_engine "https://github.com/3mper0rr/cosmicengineai/blob/main/src/engine.c"
click node_router "https://github.com/3mper0rr/cosmicengineai/blob/main/src/engine_router.c"
click node_orchestrator "https://github.com/3mper0rr/cosmicengineai/blob/main/src/orchestrator/orchestrator.cpp"
click node_backend "https://github.com/3mper0rr/cosmicengineai/blob/main/src/backend.cpp"
click node_http "https://github.com/3mper0rr/cosmicengineai/blob/main/src/http.c"
click node_bridge "https://github.com/3mper0rr/cosmicengineai/blob/main/src/bridge.cpp"
click node_config "https://github.com/3mper0rr/cosmicengineai/blob/main/src/config.h"
click node_groq_stream "https://github.com/3mper0rr/cosmicengineai/blob/main/src/providers/groq/stream.c"
click node_telemetry "https://github.com/3mper0rr/cosmicengineai/blob/main/src/telemetry.cpp"
click node_probe "https://github.com/3mper0rr/cosmicengineai/blob/main/src/probe.cpp"
click node_telemetry_c "https://github.com/3mper0rr/cosmicengineai/blob/main/src/telemetry/telemetry.c"
click node_img_backend "https://github.com/3mper0rr/cosmicengineai/blob/main/src/img_backend.c"
click node_run_img "https://github.com/3mper0rr/cosmicengineai/blob/main/tools/run_img.py"
click node_menu "https://github.com/3mper0rr/cosmicengineai/blob/main/tools/menu.sh"
click node_ollama_cloud "https://github.com/3mper0rr/cosmicengineai/blob/main/tools/ollama_cloud.sh"

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_main,node_engine,node_router,node_orchestrator,node_backend,node_http,node_bridge,node_config toneBlue
class node_telemetry,node_probe,node_telemetry_c toneAmber
class node_groq_stream toneMint
class node_img_backend toneRose
class node_run_img,node_menu,node_ollama_cloud toneIndigo
```

## Components

### Core runtime

CLI entry, routing, backend abstraction, and orchestration.

- [Main](https://github.com/3mper0rr/cosmicengineai/blob/main/src/main.c): CLI entry · Terminal entry point for the runtime. · `src/main.c`
- [Engine](https://github.com/3mper0rr/cosmicengineai/blob/main/src/engine.c): request core · Normalizes requests and drives the runtime flow. · `src/engine.c`
- [Router](https://github.com/3mper0rr/cosmicengineai/blob/main/src/engine_router.c): dispatch · Selects the execution path and backend. · `src/engine_router.c`
- [Orchestrator](https://github.com/3mper0rr/cosmicengineai/blob/main/src/orchestrator/orchestrator.cpp): coordination · Higher-level request and provider coordination. · `src/orchestrator/orchestrator.cpp`
- [Backend](https://github.com/3mper0rr/cosmicengineai/blob/main/src/backend.cpp): abstraction · Generic backend boundary for transport and execution. · `src/backend.cpp`
- [HTTP](https://github.com/3mper0rr/cosmicengineai/blob/main/src/http.c): transport · Outbound HTTP and streaming transport layer. · `src/http.c`
- [Bridge](https://github.com/3mper0rr/cosmicengineai/blob/main/src/bridge.cpp): c-c++ glue · Glue between C runtime pieces and C++ subsystems. · `src/bridge.cpp`
- [Config](https://github.com/3mper0rr/cosmicengineai/blob/main/src/config.h): settings · Compile-time and environment-driven configuration. · `src/config.h`

### Observability

Streaming inspection, telemetry, and timing probes.

- [Telemetry](https://github.com/3mper0rr/cosmicengineai/blob/main/src/telemetry.cpp): stream metrics · Streaming inspection and measurement utilities. · `src/telemetry.cpp`
- [Probe](https://github.com/3mper0rr/cosmicengineai/blob/main/src/probe.cpp): timing probe · Measures transport timing and chunk arrival. · `src/probe.cpp`
- [Telemetry C](https://github.com/3mper0rr/cosmicengineai/blob/main/src/telemetry/telemetry.c): runtime metrics · C-side telemetry support used by the runtime. · `src/telemetry/telemetry.c`

### Providers

Concrete model-provider integrations.

- [Groq stream](https://github.com/3mper0rr/cosmicengineai/blob/main/src/providers/groq/stream.c): provider adapter · Groq SSE/chunk parsing and delta extraction. · `src/providers/groq/stream.c`

### Image path

Image-generation backend and related tooling.

- [Image backend](https://github.com/3mper0rr/cosmicengineai/blob/main/src/img_backend.c): image provider · Image-generation backend integration. · `src/img_backend.c`

### Tooling

Developer and workflow scripts.

- [Run image](https://github.com/3mper0rr/cosmicengineai/blob/main/tools/run_img.py): python tool · Python helper for image-generation workflows. · `tools/run_img.py`
- [Menu](https://github.com/3mper0rr/cosmicengineai/blob/main/tools/menu.sh): shell tool · Interactive setup and workflow helper. · `tools/menu.sh`
- [Ollama cloud](https://github.com/3mper0rr/cosmicengineai/blob/main/tools/ollama_cloud.sh): shell tool · Provider/cloud workflow helper script. · `tools/ollama_cloud.sh`

## Connections

- Main → Engine: starts · CLI invokes the core request engine.
- Engine → Router: routes · Engine hands requests to the dispatch layer.
- Router → Orchestrator: coordinates · Routing delegates lifecycle and capability decisions.
- Orchestrator → Backend: selects · Orchestration chooses the execution backend.
- Backend → HTTP: uses · Backend relies on HTTP transport for outbound calls.
- HTTP → Groq stream: streams · HTTP transport feeds provider SSE/chunk parsing.
- Groq stream → Telemetry: reports · Provider streaming is observed and measured.
- Telemetry → Probe: measures · Telemetry and probe cooperate on timing/arrival metrics.
- Telemetry → Telemetry C: bridges · C and C++ telemetry layers interoperate.
- Main → Bridge: links · Native entry path connects to C++ subsystems via bridge code.
- Bridge → Orchestrator: glues · Bridge connects the C runtime to orchestration logic.
- Config → Engine: configures · Runtime settings influence request handling.
- Config → Backend: configures · Backend behavior depends on runtime configuration.
- Config → Groq stream: secrets · Provider tokens and toggles are sourced from config.
- Backend → Image backend: image path · Separate backend handles image-generation flows.
- Run image → Image backend: drives · Python helper invokes the image pipeline.
- Menu → Run image: assists · Workflow scripts support the image path.
- Ollama cloud → Orchestrator: supports · Shell workflow helpers the broader provider setup.
- Main → Image backend: optional mode · Binary can also enter the image-generation path.