# brahmastra-labs/logicaffeine architecture

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

- Interactive diagram: https://gitdiagram.com/brahmastra-labs/logicaffeine
- Repository: https://github.com/brahmastra-labs/logicaffeine

## Overview

Logicaffeine is a natural-language programming and logic system: LOGOS English is parsed into formal representations, then either translated into executable code or interpreted, or rendered as logic and used for proof. Its CLI, browser Studio, and language server expose that engine through different workflows. The README also documents multiple execution backends, verification, concurrency, and distributed data. Arrows reflect documented workflows and sampled ownership; unsampled subsystem internals are represented only where the tree and README support them.

Main entry points: [`crates/logicaffeine_compile/src/compile.rs`](https://github.com/brahmastra-labs/logicaffeine/blob/main/crates/logicaffeine_compile/src/compile.rs) (Imperative compiler), [`apps/logicaffeine_web/src/ui/app.rs`](https://github.com/brahmastra-labs/logicaffeine/blob/main/apps/logicaffeine_web/src/ui/app.rs) (Web Studio), [`crates/logicaffeine_language/src/compile.rs`](https://github.com/brahmastra-labs/logicaffeine/blob/main/crates/logicaffeine_language/src/compile.rs) (Logic compiler), [`apps/logicaffeine_cli/src/lib.rs`](https://github.com/brahmastra-labs/logicaffeine/blob/main/apps/logicaffeine_cli/src/lib.rs) (largo CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["largo CLI<br/>[lib.rs]"]
  node_studio["Web Studio<br/>[app.rs]"]
  node_lsp["Language server<br/>[server.rs]"]
  node_progress[("Browser progress<br/>[storage.rs]")]
end

subgraph group_language["Language engine"]
  node_parser["English parser<br/>[mod.rs]"]
  node_language_compile["Logic compiler<br/>[compile.rs]"]
  node_semantics["Logic semantics<br/>[mod.rs]"]
  node_analysis["Program analysis<br/>[mod.rs]"]
end

subgraph group_execution["Execution"]
  node_compiler["Imperative compiler<br/>[compile.rs]"]
  node_rust_codegen["Rust codegen<br/>[program.rs]"]
  node_interpreter["Interpreter<br/>[interpreter.rs]"]
  node_vm["Bytecode VM<br/>[machine.rs]"]
  node_jit["Native JIT<br/>[lib.rs]"]
  node_wasm["WASM backend<br/>[mod.rs]"]
end

subgraph group_reasoning["Reasoning and verification"]
  node_proof["Proof engine<br/>[engine.rs]"]
  node_kernel["Proof kernel<br/>[lib.rs]"]
  node_hardware["Hardware verification<br/>[hw_pipeline.rs]"]
end

subgraph group_distributed["Concurrency and data"]
  node_concurrency["Concurrency runtime<br/>[mod.rs]"]
  node_crdts["CRDT data types<br/>[mod.rs]"]
end

node_user(("LOGOS author"))
node_z3["Z3 verifier"]
node_libp2p["libp2p mesh"]

node_user -->|"runs commands"| node_cli
node_user -->|"writes English"| node_studio
node_user -->|"edits programs"| node_lsp
node_cli -->|"compiles logic"| node_language_compile
node_cli -->|"builds programs"| node_compiler
node_cli -->|"runs programs"| node_interpreter
node_studio -->|"logic mode"| node_language_compile
node_studio -->|"imperative mode"| node_compiler
node_studio -->|"requests proofs"| node_proof
node_studio -->|"persists progress"| node_progress
node_lsp -->|"parses documents"| node_parser
node_lsp -->|"checks programs"| node_analysis
node_parser -->|"produces formal logic"| node_language_compile
node_parser -->|"supplies program AST"| node_analysis
node_language_compile -->|"uses semantics"| node_semantics
node_compiler -->|"analyzes programs"| node_analysis
node_compiler -->|"emits Rust"| node_rust_codegen
node_compiler -->|"compiles bytecode"| node_vm
node_vm -.->|"executes fallback"| node_interpreter
node_vm -.->|"tiers up native code"| node_jit
node_compiler -->|"emits WASM"| node_wasm
node_language_compile -->|"supports proof input"| node_proof
node_proof -->|"checks proof terms"| node_kernel
node_hardware -.->|"checks equivalence"| node_z3
node_compiler -.->|"verifies hardware specs"| node_hardware
node_concurrency -->|"uses replicated types"| node_crdts
node_concurrency -.->|"connects peers"| node_libp2p

click node_cli "https://github.com/brahmastra-labs/logicaffeine/blob/main/apps/logicaffeine_cli/src/lib.rs"
click node_studio "https://github.com/brahmastra-labs/logicaffeine/blob/main/apps/logicaffeine_web/src/ui/app.rs"
click node_lsp "https://github.com/brahmastra-labs/logicaffeine/blob/main/crates/logicaffeine_lsp/src/server.rs"
click node_parser "https://github.com/brahmastra-labs/logicaffeine/blob/main/crates/logicaffeine_language/src/parser/mod.rs"
click node_language_compile "https://github.com/brahmastra-labs/logicaffeine/blob/main/crates/logicaffeine_language/src/compile.rs"
click node_semantics "https://github.com/brahmastra-labs/logicaffeine/blob/main/crates/logicaffeine_language/src/semantics/mod.rs"
click node_analysis "https://github.com/brahmastra-labs/logicaffeine/blob/main/crates/logicaffeine_compile/src/analysis/mod.rs"
click node_compiler "https://github.com/brahmastra-labs/logicaffeine/blob/main/crates/logicaffeine_compile/src/compile.rs"
click node_rust_codegen "https://github.com/brahmastra-labs/logicaffeine/blob/main/crates/logicaffeine_compile/src/codegen/program.rs"
click node_interpreter "https://github.com/brahmastra-labs/logicaffeine/blob/main/crates/logicaffeine_compile/src/interpreter.rs"
click node_vm "https://github.com/brahmastra-labs/logicaffeine/blob/main/crates/logicaffeine_compile/src/vm/machine.rs"
click node_jit "https://github.com/brahmastra-labs/logicaffeine/blob/main/crates/logicaffeine_jit/src/lib.rs"
click node_wasm "https://github.com/brahmastra-labs/logicaffeine/blob/main/crates/logicaffeine_compile/src/vm/wasm/mod.rs"
click node_proof "https://github.com/brahmastra-labs/logicaffeine/blob/main/crates/logicaffeine_proof/src/engine.rs"
click node_kernel "https://github.com/brahmastra-labs/logicaffeine/blob/main/crates/logicaffeine_kernel/src/lib.rs"
click node_hardware "https://github.com/brahmastra-labs/logicaffeine/blob/main/crates/logicaffeine_compile/src/codegen_sva/hw_pipeline.rs"
click node_concurrency "https://github.com/brahmastra-labs/logicaffeine/blob/main/crates/logicaffeine_compile/src/concurrency/mod.rs"
click node_crdts "https://github.com/brahmastra-labs/logicaffeine/blob/main/crates/logicaffeine_data/src/crdt/mod.rs"
click node_progress "https://github.com/brahmastra-labs/logicaffeine/blob/main/apps/logicaffeine_web/src/storage.rs"

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_studio,node_lsp,node_progress toneBlue
class node_parser,node_language_compile,node_semantics,node_analysis toneAmber
class node_compiler,node_rust_codegen,node_interpreter,node_vm,node_jit,node_wasm toneMint
class node_proof,node_kernel,node_hardware toneRose
class node_concurrency,node_crdts,node_user,node_z3,node_libp2p toneIndigo
```

## Components

### User interfaces

- [largo CLI](https://github.com/brahmastra-labs/logicaffeine/blob/main/apps/logicaffeine_cli/src/lib.rs): `apps/logicaffeine_cli/src/lib.rs`
- [Web Studio](https://github.com/brahmastra-labs/logicaffeine/blob/main/apps/logicaffeine_web/src/ui/app.rs): `apps/logicaffeine_web/src/ui/app.rs`
- [Language server](https://github.com/brahmastra-labs/logicaffeine/blob/main/crates/logicaffeine_lsp/src/server.rs): `crates/logicaffeine_lsp/src/server.rs`
- [Browser progress](https://github.com/brahmastra-labs/logicaffeine/blob/main/apps/logicaffeine_web/src/storage.rs): `apps/logicaffeine_web/src/storage.rs`

### Language engine

- [English parser](https://github.com/brahmastra-labs/logicaffeine/blob/main/crates/logicaffeine_language/src/parser/mod.rs): `crates/logicaffeine_language/src/parser/mod.rs`
- [Logic compiler](https://github.com/brahmastra-labs/logicaffeine/blob/main/crates/logicaffeine_language/src/compile.rs): `crates/logicaffeine_language/src/compile.rs`
- [Logic semantics](https://github.com/brahmastra-labs/logicaffeine/blob/main/crates/logicaffeine_language/src/semantics/mod.rs): `crates/logicaffeine_language/src/semantics/mod.rs`
- [Program analysis](https://github.com/brahmastra-labs/logicaffeine/blob/main/crates/logicaffeine_compile/src/analysis/mod.rs): `crates/logicaffeine_compile/src/analysis/mod.rs`

### Execution

- [Imperative compiler](https://github.com/brahmastra-labs/logicaffeine/blob/main/crates/logicaffeine_compile/src/compile.rs): `crates/logicaffeine_compile/src/compile.rs`
- [Rust codegen](https://github.com/brahmastra-labs/logicaffeine/blob/main/crates/logicaffeine_compile/src/codegen/program.rs): `crates/logicaffeine_compile/src/codegen/program.rs`
- [Interpreter](https://github.com/brahmastra-labs/logicaffeine/blob/main/crates/logicaffeine_compile/src/interpreter.rs): `crates/logicaffeine_compile/src/interpreter.rs`
- [Bytecode VM](https://github.com/brahmastra-labs/logicaffeine/blob/main/crates/logicaffeine_compile/src/vm/machine.rs): `crates/logicaffeine_compile/src/vm/machine.rs`
- [Native JIT](https://github.com/brahmastra-labs/logicaffeine/blob/main/crates/logicaffeine_jit/src/lib.rs): `crates/logicaffeine_jit/src/lib.rs`
- [WASM backend](https://github.com/brahmastra-labs/logicaffeine/blob/main/crates/logicaffeine_compile/src/vm/wasm/mod.rs): `crates/logicaffeine_compile/src/vm/wasm/mod.rs`

### Reasoning and verification

- [Proof engine](https://github.com/brahmastra-labs/logicaffeine/blob/main/crates/logicaffeine_proof/src/engine.rs): `crates/logicaffeine_proof/src/engine.rs`
- [Proof kernel](https://github.com/brahmastra-labs/logicaffeine/blob/main/crates/logicaffeine_kernel/src/lib.rs): `crates/logicaffeine_kernel/src/lib.rs`
- [Hardware verification](https://github.com/brahmastra-labs/logicaffeine/blob/main/crates/logicaffeine_compile/src/codegen_sva/hw_pipeline.rs): `crates/logicaffeine_compile/src/codegen_sva/hw_pipeline.rs`

### Concurrency and data

- [Concurrency runtime](https://github.com/brahmastra-labs/logicaffeine/blob/main/crates/logicaffeine_compile/src/concurrency/mod.rs): `crates/logicaffeine_compile/src/concurrency/mod.rs`
- [CRDT data types](https://github.com/brahmastra-labs/logicaffeine/blob/main/crates/logicaffeine_data/src/crdt/mod.rs): `crates/logicaffeine_data/src/crdt/mod.rs`

### Other components

- **LOGOS author**
- **Z3 verifier**
- **libp2p mesh**

## Connections

- LOGOS author → largo CLI: runs commands
- LOGOS author → Web Studio: writes English
- LOGOS author → Language server: edits programs
- largo CLI → Logic compiler: compiles logic
- largo CLI → Imperative compiler: builds programs
- largo CLI → Interpreter: runs programs
- Web Studio → Logic compiler: logic mode
- Web Studio → Imperative compiler: imperative mode
- Web Studio → Proof engine: requests proofs
- Web Studio → Browser progress: persists progress
- Language server → English parser: parses documents
- Language server → Program analysis: checks programs
- English parser → Logic compiler: produces formal logic
- English parser → Program analysis: supplies program AST
- Logic compiler → Logic semantics: uses semantics
- Imperative compiler → Program analysis: analyzes programs
- Imperative compiler → Rust codegen: emits Rust
- Imperative compiler → Bytecode VM: compiles bytecode
- Bytecode VM → Interpreter: executes fallback
- Bytecode VM → Native JIT: tiers up native code
- Imperative compiler → WASM backend: emits WASM
- Logic compiler → Proof engine: supports proof input
- Proof engine → Proof kernel: checks proof terms
- Hardware verification → Z3 verifier: checks equivalence
- Imperative compiler → Hardware verification: verifies hardware specs
- Concurrency runtime → CRDT data types: uses replicated types
- Concurrency runtime → libp2p mesh: connects peers