# Final Rust Crate Architecture

**Date:** 2025-10-28  
**Status:** Post-migration architecture (after comprehensive Rust migration)

> **⚠️ IMPORTANT UPDATE (December 2025):** The `feagi-data-processing` repository has been merged into `feagi-core` as workspace members:
> - `feagi-structures` → `crates/feagi-structures`
> - `feagi-serialization` → `crates/feagi-serialization`
> - `feagi-sensorimotor` → `crates/feagi-sensorimotor` (previously feagi-connector-core, then feagi-pns)
> 
> This document retains historical references to `feagi-data-processing` as a separate entity for architectural context.

---

## Crate Hierarchy Overview

```
feagi-data-processing (foundational, peer-level)
    ↓ (used by)
┌───────────────────────────────────────────────────────────────────┐
│  feagi-core (workspace with 7 subcrates)                          │
│                                                                   │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │ Full Stack Subcrates (server only):                     │    │
│  │  • feagi-api         (REST API - Axum)                  │    │
│  │  • feagi-services    (Service layer)                    │    │
│  │  • feagi-io         (I/O - ZMQ)                        │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                   │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │ Core Subcrates (reusable, modular):                     │    │
│  │  • feagi-brain-development         (Business logic)                   │    │
│  │  • feagi-npu         (Burst engine)                     │    │
│  │  • feagi-state       (State manager)                    │    │
│  │  • feagi-config      (Config loader)                    │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                   │
└───────────────────────────────────────────────────────────────────┘
    ↓ (core subcrates consumed by)
┌─────────────────────┬─────────────────────┬───────────────────────┐
│ feagi-py            │ feagi-inference-    │ feagi-web             │
│ (Python bindings)   │ engine (embedded)   │ (WASM for browser)    │
│                     │                     │                       │
│ Uses: ALL           │ Uses: npu, state,   │ Uses: npu, bdu,       │
│                     │       bdu, config   │       state           │
└─────────────────────┴─────────────────────┴───────────────────────┘
```

---

## Crate Breakdown

### 1. `feagi-data-processing` (Foundational)

**Location:** `/feagi-data-processing/`  
**Status:** ✅ Already exists  
**Role:** Foundational, peer-level crate for data structures and serialization

#### Purpose
Cross-cutting data structures used by ALL FEAGI components.

#### Key Components
```rust
// Core data structures
pub struct NeuronVoxelXYZPArrays { /* ... */ }
pub struct SensoryData { /* ... */ }
pub struct MotorData { /* ... */ }

// Serialization formats
pub mod serialization {
    pub fn serialize_xyzp(...);
    pub fn deserialize_xyzp(...);
    pub fn compress_lz4(...);
}
```

#### Used By
- ✅ `feagi-core` (BDU, NPU, API)
- ✅ `brain-visualizer` (Godot client)
- ✅ `feagi-connector` (agents)
- ✅ `feagi-inference-engine` (embedded)
- ✅ Python bindings

#### Dependencies
```toml
[dependencies]
serde = "1.0"
serde_json = "1.0"
lz4 = "1.24"
ndarray = "0.15"  # For array operations
```

**Size:** ~5,000 LOC

---

### 2. `feagi-core` (Main Application Workspace)

**Location:** `/feagi-core/`  
**Status:** 🔄 Will be the result of this migration  
**Role:** Workspace containing 7 subcrates (3 full-stack, 4 reusable core)

#### Purpose
Modular workspace enabling full FEAGI server while providing reusable core components for embedded and WASM deployments.

#### Workspace Structure
```
feagi-core/
├── Cargo.toml                     # Workspace definition
├── src/
│   └── main.rs                    # Binary that composes all subcrates
│
├── crates/                        # 7 SUBCRATES
│   │
│   ├── feagi-api/                 # REST API (Axum) - Full Stack Only
│   │   ├── Cargo.toml
│   │   └── src/
│   │       ├── lib.rs
│   │       ├── app.rs             # Axum app setup
│   │       ├── endpoints/         # REST endpoints
│   │       │   ├── system.rs
│   │       │   ├── cortical_area.rs
│   │       │   ├── genome.rs
│   │       │   └── ...
│   │       ├── middleware/        # Auth, CORS, error handling
│   │       └── models/            # Request/response DTOs
│   │
│   ├── feagi-services/            # Service Layer - Full Stack Only
│   │   ├── Cargo.toml
│   │   └── src/
│   │       ├── lib.rs
│   │       ├── base_service.rs    # BaseService trait
│   │       ├── core_api_service.rs # Facade
│   │       ├── system_service.rs
│   │       ├── genome_service.rs
│   │       ├── cortical_area_service.rs
│   │       ├── connectome_service.rs
│   │       ├── brain_service.rs
│   │       ├── agents_service.rs
│   │       ├── network_service.rs
│   │       └── npu_service.rs
│   │
│   ├── feagi-brain-development/                 # Business Logic - CORE (Reusable)
│   │   ├── Cargo.toml             # Features: std, minimal, full, wasm
│   │   └── src/
│   │       ├── lib.rs
│   │       ├── connectome_manager.rs
│   │       ├── embryogenesis/     # Genome loading
│   │       ├── models/            # CorticalArea, BrainRegion
│   │       ├── cortical_mapping.rs
│   │       └── utils/             # Metrics, position utils
│   │
│   ├── feagi-npu/                 # Burst Engine - CORE (Reusable)
│   │   ├── Cargo.toml             # Features: std, no_std, gpu, wasm
│   │   └── src/
│   │       ├── lib.rs
│   │       ├── burst_engine.rs    # Already exists
│   │       ├── neuron_pool.rs
│   │       └── synapse_manager.rs
│   │
│   ├── feagi-state/               # State Manager - CORE (Reusable)
│   │   ├── Cargo.toml             # Features: std, no_std
│   │   └── src/
│   │       ├── lib.rs
│   │       ├── state_manager.rs   # Already migrated to Rust
│   │       └── atomic_state.rs
│   │
│   ├── feagi-io/                 # I/O Streams - Full Stack Only
│   │   ├── Cargo.toml             # ZMQ, not WASM compatible
│   │   └── src/
│   │       ├── lib.rs
│   │       ├── zmq_streams.rs     # Already exists
│   │       └── sensory_injection.rs
│   │
│   └── feagi-config/              # Config Loader - CORE (Reusable)
│       ├── Cargo.toml             # Features: std, no_std
│       └── src/
│           ├── lib.rs
│           └── toml_loader.rs
│
└── tests/
    ├── integration/
    └── benches/
```

#### Key Features
- ✅ REST API (50-60 endpoints)
- ✅ WebSocket support (for Brain Visualizer)
- ✅ ZMQ streams (sensory, motor, visualization, control)
- ✅ Genome loading (neuroembryogenesis)
- ✅ Burst engine (neural processing)
- ✅ State management
- ✅ Agent management
- ✅ OpenAPI documentation

#### Main Binary Dependencies
```toml
# feagi-core/Cargo.toml (main binary)
[workspace]
members = [
    "crates/feagi-api",
    "crates/feagi-services",
    "crates/feagi-brain-development",
    "crates/feagi-npu",
    "crates/feagi-state",
    "crates/feagi-io",
    "crates/feagi-config",
]

[dependencies]
# All subcrates (full stack)
feagi-api = { path = "crates/feagi-api" }
feagi-services = { path = "crates/feagi-services" }
feagi-brain-development = { path = "crates/feagi-brain-development", features = ["full"] }
feagi-npu = { path = "crates/feagi-npu", features = ["gpu"] }
feagi-state = { path = "crates/feagi-state" }
feagi-io = { path = "crates/feagi-io" }
feagi-config = { path = "crates/feagi-config" }

# Async runtime
tokio = { version = "1", features = ["full"] }
```

#### Individual Subcrate Dependencies

**feagi-api/Cargo.toml:**
```toml
[dependencies]
feagi-services = { path = "../feagi-services" }
axum = "0.7"
tower = "0.4"
tower-http = { version = "0.5", features = ["cors", "trace"] }
utoipa = "4"
utoipa-swagger-ui = "6"
serde = { version = "1", features = ["derive"] }
validator = "0.16"
```

**feagi-services/Cargo.toml:**
```toml
[dependencies]
feagi-brain-development = { path = "../feagi-brain-development" }
feagi-npu = { path = "../feagi-npu" }
feagi-state = { path = "../feagi-state" }
parking_lot = "0.12"
```

**feagi-brain-development/Cargo.toml:**
```toml
[dependencies]
feagi-data-processing = { path = "../../feagi-data-processing" }
serde = { version = "1", features = ["derive"] }
petgraph = { version = "0.6", optional = true }  # For hierarchy

[features]
default = ["std", "full"]
std = []
full = ["embryogenesis", "genome-loading", "petgraph"]
minimal = []  # For inference engine
wasm = []
embryogenesis = []
genome-loading = []
```

**feagi-npu/Cargo.toml:**
```toml
[dependencies]
feagi-data-processing = { path = "../../feagi-data-processing" }
feagi-state = { path = "../feagi-state" }
ndarray = "0.15"
parking_lot = { version = "0.12", optional = true }

[features]
default = ["std", "gpu"]
std = ["parking_lot"]
no_std = []
gpu = ["wgpu"]
wasm = ["wasm-bindgen"]

[dependencies.wgpu]
version = "0.19"
optional = true
```

**feagi-state/Cargo.toml:**
```toml
[dependencies]
parking_lot = { version = "0.12", optional = true }
serde = { version = "1", features = ["derive"] }

[features]
default = ["std"]
std = ["parking_lot"]
no_std = []
```

**feagi-io/Cargo.toml:**
```toml
[dependencies]
feagi-npu = { path = "../feagi-npu" }
feagi-state = { path = "../feagi-state" }
zeromq = "0.4.1"
tokio-tungstenite = "0.21"  # WebSocket
```

**feagi-config/Cargo.toml:**
```toml
[dependencies]
serde = { version = "1", features = ["derive"] }
toml = { version = "0.8", optional = true }

[features]
default = ["std"]
std = ["toml"]
no_std = []
```

**Size:** ~30,000-40,000 LOC

#### Binary Output
```bash
cargo build --release
# Produces: target/release/feagi-core (20-50MB)
```

---

### 3. `feagi-inference-engine` (Embedded/RTOS)

**Location:** `/feagi-inference-engine/`  
**Status:** ✅ Already exists (will be enhanced)  
**Role:** Minimal, `no_std` compatible inference engine for embedded systems

#### Purpose
Lightweight inference-only engine for resource-constrained environments.

#### Features
- ✅ `no_std` compatible
- ✅ No heap allocation (or minimal)
- ✅ Inference only (no training)
- ✅ Pre-trained model loading
- ✅ RTOS compatible

#### Structure
```rust
// feagi-inference-engine/src/lib.rs

#![no_std]  // Embedded compatibility

pub struct InferenceEngine {
    neurons: &'static [Neuron],
    synapses: &'static [Synapse],
}

impl InferenceEngine {
    pub fn from_serialized(data: &[u8]) -> Self { /* ... */ }
    pub fn process_input(&mut self, input: &[f32]) -> &[f32] { /* ... */ }
}
```

#### Dependencies (Selective Core Subcrates)
```toml
[dependencies]
# Foundational
feagi-data-processing = { path = "../feagi-data-processing", default-features = false }

# Core subcrates from feagi-core (SELECTIVE)
feagi-npu = { path = "../feagi-core/crates/feagi-npu", default-features = false, features = ["no_std"] }
feagi-state = { path = "../feagi-core/crates/feagi-state", default-features = false, features = ["no_std"] }
feagi-brain-development = { path = "../feagi-core/crates/feagi-brain-development", default-features = false, features = ["minimal"] }
feagi-config = { path = "../feagi-core/crates/feagi-config", default-features = false }

# NO feagi-api (not needed)
# NO feagi-services (not needed)
# NO feagi-io (ZMQ incompatible with embedded)

# Embedded-specific
heapless = "0.8"  # Fixed-size collections for no_std

[features]
default = ["std"]
std = []
```

**Key Point:** Uses only 4 core subcrates, NOT the full-stack subcrates (api, services, pns)

**Size:** ~3,000-5,000 LOC

#### Use Cases
- ✅ Microcontrollers (ARM Cortex-M)
- ✅ RTOS systems (FreeRTOS, Zephyr)
- ✅ Edge devices
- ✅ Real-time control systems

---

### 4. `feagi-web` (WASM for Browser) 🆕

**Location:** `/feagi-web/` (to be created)  
**Status:** 🔮 Future (not in 5-month plan)  
**Role:** WASM-compiled FEAGI for browser-based inference

#### Purpose
Run FEAGI inference in web browsers via WebAssembly.

#### Features
- ✅ WASM compilation
- ✅ Browser-compatible
- ✅ WebGPU support (optional)
- ✅ Inference only
- ✅ Interactive demos

#### Structure
```rust
// feagi-web/src/lib.rs

use wasm_bindgen::prelude::*;

#[wasm_bindgen]
pub struct FEAGIWeb {
    npu: NPU,
    bdu: BDU,
}

#[wasm_bindgen]
impl FEAGIWeb {
    pub fn new(model_data: &[u8]) -> Self { /* ... */ }
    pub fn process(&mut self, input: Vec<f32>) -> Vec<f32> { /* ... */ }
}
```

#### Dependencies (Selective Core Subcrates)
```toml
[dependencies]
# Foundational
feagi-data-processing = { path = "../feagi-data-processing", default-features = false }

# Core subcrates from feagi-core (SELECTIVE)
feagi-npu = { path = "../feagi-core/crates/feagi-npu", features = ["wasm"] }
feagi-brain-development = { path = "../feagi-core/crates/feagi-brain-development", features = ["wasm", "minimal"] }
feagi-state = { path = "../feagi-core/crates/feagi-state" }

# NO feagi-api (browser uses wasm-bindgen instead)
# NO feagi-services (not needed for inference)
# NO feagi-io (ZMQ incompatible with WASM)
# NO feagi-config (config passed via JS)

# WASM-specific
wasm-bindgen = "0.2"
js-sys = "0.3"
web-sys = { version = "0.3", features = ["WebGl2RenderingContext", "WebGpuContext"] }

[lib]
crate-type = ["cdylib"]
```

**Key Point:** Uses only 3 core subcrates (npu, bdu, state), NOT the full-stack subcrates

**Size:** ~2,000-3,000 LOC

#### Build Output
```bash
wasm-pack build --target web
# Produces: pkg/feagi_web_bg.wasm (~500KB compressed)
```

---

### 5. `feagi-py` (Python Bindings) 🔄

**Location:** `/feagi-rust-py-libs/` (will be renamed to `/feagi-py/`)  
**Status:** 🔄 Will be restructured  
**Role:** Python bindings for Rust `feagi-core`

#### Purpose
Expose Rust FEAGI to Python for scripting, notebooks, and legacy compatibility.

#### Features
- ✅ PyO3 bindings
- ✅ Python-friendly API
- ✅ Jupyter notebook support
- ✅ Backward compatibility layer (during transition)

#### Structure
```rust
// feagi-py/src/lib.rs

use pyo3::prelude::*;

#[pyclass]
struct PyConnectomeManager { /* ... */ }

#[pyclass]
struct PyCorticalArea { /* ... */ }

#[pyfunction]
fn start_feagi_server(config_path: String) -> PyResult<()> {
    // Start Rust FEAGI server from Python
}

#[pymodule]
fn feagi(_py: Python, m: &PyModule) -> PyResult<()> {
    m.add_class::<PyConnectomeManager>()?;
    m.add_class::<PyCorticalArea>()?;
    m.add_function(wrap_pyfunction!(start_feagi_server, m)?)?;
    Ok(())
}
```

#### Dependencies
```toml
[dependencies]
feagi-core = { path = "../feagi-core" }
feagi-data-processing = { path = "../feagi-data-processing" }
pyo3 = { version = "0.20", features = ["extension-module"] }
```

**Size:** ~3,000-5,000 LOC

#### Python Usage
```python
import feagi

# Start server
feagi.start_feagi_server("config.toml")

# Or use as library
manager = feagi.ConnectomeManager.instance()
area = feagi.CorticalArea(
    cortical_id="test",
    dimensions=(10, 10, 10),
)
manager.add_cortical_area(area)
```

---

## Supporting Crates (Already Exist)

### 6. `brain-visualizer` (Godot + Rust)

**Location:** `/brain-visualizer/`  
**Status:** ✅ Already exists  
**Role:** 3D visualization client

#### Components
- Godot 4 (C++)
- Rust extensions for performance
- Uses `feagi-data-processing` for data

**Not migrating** - already optimized

---

### 7. `feagi-connector` (Python, will stay)

**Location:** `/feagi-connector/`  
**Status:** ✅ Keep in Python  
**Role:** Agent development SDK

#### Purpose
SDK for building FEAGI agents (sensors/motors).

**Keep in Python** because:
- User-facing SDK (Python is more accessible)
- Rapid prototyping
- Community contributions
- Legacy agent compatibility

**Uses:** `feagi-data-processing` for data exchange

---

### 8. `feagi-bridge` (Python, will stay)

**Location:** `/feagi_bridge/`  
**Status:** ✅ Keep in Python  
**Role:** Bridge between FEAGI and Brain Visualizer

**Keep in Python** because:
- Stable and working
- Not performance-critical
- Plugin architecture in Python

---

## Final Crate Summary Table

### Top-Level Crates

| Crate | Language | Purpose | Size | Status | Priority |
|-------|----------|---------|------|--------|----------|
| **feagi-data-processing** | Rust | Data structures, serialization | 5K LOC | ✅ Exists | P0 |
| **feagi-core** | Rust | Workspace with 7 subcrates | 40K LOC | 🔄 Migrate | P0 |
| **feagi-inference-engine** | Rust | Embedded inference | 5K LOC | ✅ Exists | P1 |
| **feagi-py** | Rust+Python | Python bindings | 5K LOC | 🔄 Restructure | P1 |
| **feagi-web** | Rust+WASM | Browser inference | 3K LOC | 🔮 Future | P2 |
| **brain-visualizer** | Godot+Rust | 3D visualization | 20K LOC | ✅ Keep | - |
| **feagi-connector** | Python | Agent SDK | 10K LOC | ✅ Keep | - |
| **feagi-bridge** | Python | BV bridge | 5K LOC | ✅ Keep | - |

### `feagi-core` Subcrates (7 Subcrates)

| Subcrate | Type | Purpose | Used By | Size |
|----------|------|---------|---------|------|
| **feagi-api** | Full Stack | REST API (Axum) | feagi-core only | 8K LOC |
| **feagi-services** | Full Stack | Service layer | feagi-core only | 10K LOC |
| **feagi-io** | Full Stack | I/O (ZMQ, WebSocket) | feagi-core only | 3K LOC |
| **feagi-brain-development** | Core (Reusable) | Business logic | ALL projects | 10K LOC |
| **feagi-npu** | Core (Reusable) | Burst engine | ALL projects | 5K LOC |
| **feagi-state** | Core (Reusable) | State manager | ALL projects | 2K LOC |
| **feagi-config** | Core (Reusable) | Config loader | feagi-core, inference-engine | 2K LOC |

---

## Dependency Graph

```
                    ┌─────────────────────────┐
                    │ feagi-data-processing   │ (foundational)
                    │ - Data structures       │
                    │ - Serialization         │
                    └───────────┬─────────────┘
                                │
                                │ (used by all)
                                ↓
        ┌───────────────────────┼───────────────────────┐
        │                       │                       │
┌───────▼─────────┐    ┌────────▼────────┐    ┌────────▼────────┐
│ feagi-core      │    │ feagi-inference-│    │ feagi-web       │
│ (main server)   │    │ engine          │    │ (WASM)          │
│                 │    │ (embedded)      │    │                 │
│ - API (Axum)    │    │ - no_std        │    │ - WebAssembly   │
│ - Services      │    │ - RTOS ready    │    │ - WebGPU        │
│ - BDU           │    └─────────────────┘    └─────────────────┘
│ - NPU           │
│ - State Manager │
│ - PNS (I/O)     │
└────────┬────────┘
         │
         │ (exposes via PyO3)
         ↓
┌─────────────────┐
│ feagi-py        │
│ (Python binding)│
└─────────────────┘
```

---

## Workspace Structure

```
/Users/nadji/code/FEAGI-2.0/
│
├── feagi-data-processing/     # Foundational data crate
│   ├── Cargo.toml
│   ├── src/
│   └── tests/
│
├── feagi-core/                 # Main application workspace ⭐
│   ├── Cargo.toml             # Workspace definition
│   ├── src/
│   │   └── main.rs            # Binary that uses all subcrates
│   │
│   ├── crates/                # 7 SUBCRATES
│   │   ├── feagi-api/         # REST API (Axum)
│   │   │   ├── Cargo.toml
│   │   │   └── src/
│   │   │
│   │   ├── feagi-services/    # Service layer
│   │   │   ├── Cargo.toml
│   │   │   └── src/
│   │   │
│   │   ├── feagi-brain-development/         # Business logic (CORE - reusable)
│   │   │   ├── Cargo.toml
│   │   │   └── src/
│   │   │
│   │   ├── feagi-npu/         # Burst engine (CORE - reusable)
│   │   │   ├── Cargo.toml
│   │   │   └── src/
│   │   │
│   │   ├── feagi-state/       # State manager (CORE - reusable)
│   │   │   ├── Cargo.toml
│   │   │   └── src/
│   │   │
│   │   ├── feagi-io/         # I/O streams (ZMQ)
│   │   │   ├── Cargo.toml
│   │   │   └── src/
│   │   │
│   │   └── feagi-config/      # Config loader (CORE - reusable)
│   │       ├── Cargo.toml
│   │       └── src/
│   │
│   ├── tests/
│   └── benches/
│
├── feagi-inference-engine/    # Embedded inference
│   ├── Cargo.toml             # Uses: feagi-npu, feagi-state, feagi-brain-development, feagi-config
│   └── src/
│
├── feagi-py/                   # Python bindings
│   ├── Cargo.toml             # Uses: ALL feagi-core subcrates
│   ├── pyproject.toml
│   ├── src/                   # Rust PyO3 code
│   └── python/                # Python wrapper code
│
├── feagi-web/                  # WASM (future)
│   ├── Cargo.toml             # Uses: feagi-npu, feagi-brain-development, feagi-state
│   ├── src/
│   └── www/                   # JS/HTML demo
│
├── brain-visualizer/           # Godot + Rust (keep as-is)
│
├── feagi-connector/            # Python SDK (keep)
│
├── feagi_bridge/               # Python bridge (keep)
│
└── Cargo.toml                  # Root workspace

# Root Workspace Cargo.toml
[workspace]
members = [
    "feagi-data-processing",
    "feagi-core",
    "feagi-core/crates/feagi-api",
    "feagi-core/crates/feagi-services",
    "feagi-core/crates/feagi-brain-development",
    "feagi-core/crates/feagi-npu",
    "feagi-core/crates/feagi-state",
    "feagi-core/crates/feagi-io",
    "feagi-core/crates/feagi-config",
    "feagi-inference-engine",
    "feagi-py",
    "feagi-web",
]
```

---

## Build & Deploy

### Development
```bash
# Build all workspace crates
cargo build --workspace

# Test all
cargo test --workspace

# Lint all
cargo clippy --workspace
```

### Production
```bash
# Build main server (optimized)
cd feagi-core
cargo build --release

# Result: target/release/feagi-core (20-50MB binary)
```

### Python Bindings
```bash
cd feagi-py
maturin develop  # Development
maturin build --release  # Production wheel
pip install target/wheels/feagi-*.whl
```

### WASM
```bash
cd feagi-web
wasm-pack build --target web
# Result: pkg/feagi_web_bg.wasm
```

---

## Migration Impact on Crates

### Before Migration (Current)
- `feagi-py/` - 100K+ LOC Python
- `feagi-core/` - Small Rust NPU only
- Multiple scattered Python modules

### After Migration (Target)
- `feagi-core/` - 40K LOC Rust (everything)
- `feagi-py/` - 5K LOC Rust+Python (bindings only)
- Clean, unified architecture

**Total Rust LOC:** ~60K (from ~10K)  
**Total Python LOC:** ~15K (from ~100K+)  
**Reduction:** ~85% less Python code

---

## Key Decisions

### ✅ Confirmed
1. **feagi-core** - Main crate with all server logic
2. **feagi-data-processing** - Foundational, peer-level
3. **feagi-inference-engine** - Embedded/RTOS
4. **feagi-py** - Python bindings only
5. Keep `feagi-connector`, `feagi-bridge` in Python

### 🔮 Future (Post 5-month migration)
1. **feagi-web** - WASM for browser
2. Move BDU (genome evolution) to separate crate?
3. Training/evolution crate?

---

## Key Benefits of Modular Subcrate Architecture

### 1. **Selective Dependency Resolution**
```toml
# feagi-inference-engine only needs 4 subcrates
feagi-npu = { path = "../feagi-core/crates/feagi-npu", features = ["no_std"] }
feagi-state = { path = "../feagi-core/crates/feagi-state", features = ["no_std"] }
feagi-brain-development = { path = "../feagi-core/crates/feagi-brain-development", features = ["minimal"] }
feagi-config = { path = "../feagi-core/crates/feagi-config" }

# Excludes: feagi-api, feagi-services, feagi-io (not needed for embedded)
```

### 2. **Feature Flag Flexibility**
- **Full Stack:** `feagi-core` uses all features (`std`, `gpu`, `full`)
- **Embedded:** `feagi-inference-engine` uses minimal features (`no_std`, `minimal`)
- **WASM:** `feagi-web` uses browser features (`wasm`, `minimal`)

### 3. **Faster Incremental Builds**
- Change `feagi-api` → only rebuild API layer
- Change `feagi-npu` → rebuild NPU + dependents (services, main binary)
- Change `feagi-brain-development` → rebuild BDU + all consumers

### 4. **Clear Boundaries**
- **Full Stack subcrates** (api, services, pns) → Server-only
- **Core subcrates** (bdu, npu, state, config) → Reusable everywhere
- API layer CANNOT directly access NPU (enforced by Rust)

### 5. **Platform-Specific Compilation**
```rust
// feagi-npu with conditional compilation
#[cfg(feature = "std")]
use parking_lot::RwLock;

#[cfg(not(feature = "std"))]
use spin::RwLock;  // For no_std environments

#[cfg(feature = "wasm")]
use wasm_bindgen::prelude::*;
```

### 6. **Binary Size Optimization**
- **Full server:** 20-50MB (includes everything)
- **Embedded:** 500KB-2MB (only core subcrates)
- **WASM:** 500KB (minimal, compressed)

### 7. **Future-Proof Extensibility**
Need a new deployment target? Just pick the subcrates you need:
- ✅ Mobile app? Use `feagi-npu` + `feagi-brain-development`
- ✅ CLI tool? Use `feagi-config` + `feagi-brain-development`
- ✅ Distributed cluster? Use `feagi-npu` + custom orchestration

---

## Conclusion

**Final crate count: 5 top-level + 7 subcrates**

**Top-Level Crates (5):**
1. `feagi-data-processing` (foundational)
2. `feagi-core` (workspace with 7 subcrates)
3. `feagi-inference-engine` (embedded)
4. `feagi-py` (Python bindings)
5. `feagi-web` (WASM - future)

**`feagi-core` Subcrates (7):**
- **Full Stack (3):** feagi-api, feagi-services, feagi-io
- **Core/Reusable (4):** feagi-brain-development, feagi-npu, feagi-state, feagi-config

**Supporting (3):**
6. `brain-visualizer` (Godot+Rust - keep)
7. `feagi-connector` (Python - keep)
8. `feagi_bridge` (Python - keep)

**This modular architecture enables:**
- ✅ Full FEAGI server (all subcrates)
- ✅ Embedded inference (4 core subcrates)
- ✅ Browser WASM (3 core subcrates)
- ✅ Python bindings (all subcrates)
- ✅ Future extensibility (pick what you need)

**Clean, hierarchical, modular, and reusable!** 🦀

