Architecture map

The map on the Engineering page is a source navigation tool. It is not a deployment diagram or a claim that all services start together.

Repository shape

The reviewed tree has a React/TypeScript/Vite application under LokiAi/, a separately packaged Node/Express API under LokiAi/backend/, and a frontend agent-orchestration module. MongoDB-oriented client/model paths and Socket.IO server setup are also present, but their external connection and deployed data path were not verified. Python components live in their own directories: portfolio_rebalancer/ contains the simulated allocation workflow, while task_gateway/ contains a FastAPI/Celery service. The Solidity sources and Hardhat scripts are under loki-contracts/.

The root README describes a broader, evolving stack, including a Rust-oriented backend and PostgreSQL migrations. The nested package manifests show current Node and Python entrypoints as well. Read the manifest and entrypoint for the package you plan to use; do not infer the active runtime from a folder name or an older summary.

Two source paths

Interface to service-shaped code: the React app contains portfolio, agent, and cross-chain views. The repository also defines an agent orchestrator and an Express server. The source map relates those files for inspection, but this review did not start a complete production stack or verify every request across the boundary. Some displayed states are explicitly simulated.

Rebalance proposal to execution boundary: the Python engine compares allocation state and describes a simulated trade path. A related Solidity contract file exists, but the Python simulation is not evidence that the contract was called, that a bridge transferred an asset, or that a transaction settled.

Reading the map

The interactive diagram is keyboard-operable. Selecting a node updates the evidence panel and reveals pinned source links. A text equivalent appears beneath it, so the component list and its limitations remain readable without JavaScript or pointer interaction. Dashed edges mean source-level or unverified relationships; the separate research node is intentionally not connected to the application path.

The source map is pinned to commit b7207a8177b4d9a564bf3596b8c450372d5d050b, reviewed on 2026-11-04. The global GitHub link follows the repository’s latest default branch, while evidence links in the map stay pinned to that review.

Package boundaries

• Browser UI: Vite owns the development server for the React application.
• Node API: the backend package owns its Express entrypoint, environment, and server script.
• Python services: the task gateway and portfolio workflow have separate dependency and runtime requirements.
• Persistence and events: MongoDB-related service/model code and Socket.IO server setup are present, but a production database connection or event subscription was not verified.
• Contracts: Hardhat compile/test scripts are scoped to the Solidity package. Deployment commands are intentionally not part of the getting-started flow.
• Infrastructure: root and LokiAi/ contain multiple Compose variants and NGINX configurations. They are alternatives with package-specific assumptions, not one verified all-in-one startup path.

A directory in the same repository is not necessarily a service dependency. Check each package’s README, manifest, environment requirements, and callers before wiring it into a release.