> ## Documentation Index
> Fetch the complete documentation index at: https://pessoal-86816071.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture Overview

> High-level architecture for the Build a Bear Vault, including the on-chain vault, off-chain solver, and protocol execution path.

# Architecture Overview

The system is split into two layers:

* `on-chain enforcement`
* `off-chain intelligence and execution`

This separation is intentional. The optimizer is computationally heavy, while the vault contract should stay deterministic, auditable, and relatively small.

## End-to-end shape

1. Users deposit `USDC` into the vault
2. The solver computes target allocations off-chain
3. Ranger builds protocol-specific transaction bundles
4. The program stores the approved rebalance proof
5. Protocol transactions are executed
6. The program records the execution proof and updates allocation state

## Why this split exists

### On-chain should enforce

The program is responsible for:

* vault state
* shares and treasury accounting
* policy boundaries
* strategy registry
* withdrawal lifecycle
* rebalance proof storage

### Off-chain should decide

The off-chain stack is responsible for:

* data gathering
* scoring strategies
* computing target weights
* building protocol instructions
* bundling transactions
* orchestrating retries and operator workflows

## Design principles

### Policy before optimization

No strategy can be selected beyond the configured policy envelopes.

### Deterministic before adaptive

The first version uses deterministic math and explicit haircuts, not ML or opaque heuristics.

### Proofs on-chain, heavy compute off-chain

Only the approved plan and execution proof are committed on-chain.

## Main modules

| Module                           | Role                                             |
| -------------------------------- | ------------------------------------------------ |
| `programs/multi_strategy_vault/` | On-chain program and account model               |
| `services/adapters/`             | Protocol-specific execution builders             |
| `services/solver/`               | Strategy scoring and rebalance plan generation   |
| `services/ranger/`               | Execution runtime, vault clients, operator CLIs  |
| `services/shared/`               | Shared types, configs, hashes, math, env loading |

## Read next

* [On-chain Architecture](./onchain)
* [Off-chain Architecture](./offchain)
* [Solver Deep Dive](./solver)
* [Rebalance Flow](./rebalance-flow)