# useplx/synapse architecture

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

- Interactive diagram: https://gitdiagram.com/useplx/synapse
- Repository: https://github.com/useplx/synapse

## Overview

SYNaPSe is a PLeX project and package manager: users initialize or configure a project, resolve dependencies and capability bindings, inspect the resulting plan, then build packages into a deployable .mln artifact. The graph preserves README capabilities such as package composition, hooks, policy/device configuration, weight conversion, and multi-language toolchains. Source excerpts show CLI dispatch, manifest parsing, dependency traversal, compiler graph emission, and toolchain process use; other documented subsystem links are dashed where implementation was not sampled.

Main entry points: [`src/compiler/compiler.cpp`](https://github.com/useplx/synapse/blob/main/src/compiler/compiler.cpp) (Graph compiler), [`src/cli/compiler_plan.cpp`](https://github.com/useplx/synapse/blob/main/src/cli/compiler_plan.cpp) (Build plan), [`src/package/resolver.cpp`](https://github.com/useplx/synapse/blob/main/src/package/resolver.cpp) (Dependency resolver), [`src/main.cpp`](https://github.com/useplx/synapse/blob/main/src/main.cpp) (Command dispatch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI workflow"]
  node_cli["Command dispatch<br/>[main.cpp]"]
  node_project_commands["Project commands"]
  node_build_command["Build command<br/>[build.cpp]"]
  node_inspect_graph["Inspect and graph"]
end

subgraph group_project["Project and packages"]
  node_manifest["Project manifest<br/>[project.cpp]"]
  node_value["Typed configuration<br/>[value.cpp]"]
  node_resolver["Dependency resolver<br/>[resolver.cpp]"]
  node_lockfile["Dependency lockfile<br/>[lockfile.cpp]"]
  node_registry["Package registry"]
  node_plan["Build plan<br/>[compiler_plan.cpp]"]
  node_composition["Package composition<br/>[package.hpp]"]
  node_hooks_policies["Hooks and policies<br/>[compiler.hpp]"]
end

subgraph group_build["Compilation and artifacts"]
  node_compiler_api["Compiler API<br/>[compiler_api.cpp]"]
  node_compiler["Graph compiler<br/>[compiler.cpp]"]
  node_operation_emission["Operation lowering<br/>[operations.hpp]"]
  node_functional_ops["Functional operations"]
  node_backend["Backend selection<br/>[backend.cpp]"]
  node_weights["Weight conversion<br/>[weights_pack.cpp]"]
  node_artifact["Artifact and deployment<br/>[artifact.cpp]"]
end

subgraph group_toolchains["Toolchains"]
  node_toolchain_registry["Toolchain selection<br/>[driver.cpp]"]
  node_language_drivers["Language drivers"]
  node_process["External processes<br/>[process.cpp]"]
end

node_user(("Project author"))
node_mln{{"MyeLiN SDK/runtime"}}
node_compiler_library{{"Compiler library"}}
node_toolchain_tools{{"Language toolchains"}}
node_output[("MLN artifact")]

node_user -->|"invokes"| node_cli
node_cli -.->|"dispatches"| node_project_commands
node_cli -.->|"dispatches"| node_build_command
node_cli -.->|"dispatches"| node_inspect_graph
node_project_commands -.->|"configures"| node_manifest
node_build_command -.->|"loads"| node_manifest
node_manifest -->|"parses values"| node_value
node_resolver -->|"loads packages"| node_manifest
node_resolver -.->|"writes lock"| node_lockfile
node_resolver -.->|"resolves packages"| node_registry
node_inspect_graph -.->|"resolves project"| node_resolver
node_inspect_graph -.->|"prints plan"| node_plan
node_build_command -->|"prepares plan"| node_plan
node_plan -->|"resolves dependencies"| node_resolver
node_plan -.->|"selects toolchains"| node_toolchain_registry
node_plan -.->|"composes packages"| node_composition
node_build_command -.->|"requests compilation"| node_compiler_api
node_compiler_api -->|"compiles request"| node_compiler
node_compiler -->|"emits graph"| node_operation_emission
node_operation_emission -->|"dispatches emitters"| node_functional_ops
node_compiler -->|"applies configuration"| node_hooks_policies
node_compiler -.->|"selects backend"| node_backend
node_compiler -.->|"converts weights"| node_weights
node_compiler -.->|"produces package"| node_artifact
node_compiler_api -->|"uses SDK"| node_mln
node_artifact -.->|"writes artifact"| node_output
node_toolchain_registry -->|"selects driver"| node_language_drivers
node_language_drivers -->|"runs commands"| node_process
node_process -.->|"executes"| node_toolchain_tools

click node_cli "https://github.com/useplx/synapse/blob/main/src/main.cpp"
click node_project_commands "https://github.com/useplx/synapse/tree/main/src/cli"
click node_build_command "https://github.com/useplx/synapse/blob/main/src/cli/build.cpp"
click node_inspect_graph "https://github.com/useplx/synapse/tree/main/src/cli"
click node_manifest "https://github.com/useplx/synapse/blob/main/src/config/project.cpp"
click node_value "https://github.com/useplx/synapse/blob/main/src/config/value.cpp"
click node_resolver "https://github.com/useplx/synapse/blob/main/src/package/resolver.cpp"
click node_lockfile "https://github.com/useplx/synapse/blob/main/src/package/lockfile.cpp"
click node_registry "https://github.com/useplx/synapse/blob/main/src/compiler/package_registry.cpp"
click node_plan "https://github.com/useplx/synapse/blob/main/src/cli/compiler_plan.cpp"
click node_composition "https://github.com/useplx/synapse/blob/main/include/syn/package.hpp"
click node_hooks_policies "https://github.com/useplx/synapse/blob/main/include/syn/compiler.hpp"
click node_compiler_api "https://github.com/useplx/synapse/blob/main/src/compiler/compiler_api.cpp"
click node_compiler "https://github.com/useplx/synapse/blob/main/src/compiler/compiler.cpp"
click node_operation_emission "https://github.com/useplx/synapse/blob/main/include/syn/operations.hpp"
click node_functional_ops "https://github.com/useplx/synapse/tree/main/src/compiler/functional"
click node_backend "https://github.com/useplx/synapse/blob/main/src/compiler/backend.cpp"
click node_weights "https://github.com/useplx/synapse/blob/main/src/compiler/weights_pack.cpp"
click node_artifact "https://github.com/useplx/synapse/blob/main/src/compiler/artifact.cpp"
click node_toolchain_registry "https://github.com/useplx/synapse/blob/main/src/toolchain/driver.cpp"
click node_language_drivers "https://github.com/useplx/synapse/tree/main/src/toolchain"
click node_process "https://github.com/useplx/synapse/blob/main/src/system/process.cpp"

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_project_commands,node_build_command,node_inspect_graph toneBlue
class node_manifest,node_value,node_resolver,node_lockfile,node_registry,node_plan,node_composition,node_hooks_policies,node_output toneAmber
class node_compiler_api,node_compiler,node_operation_emission,node_functional_ops,node_backend,node_weights,node_artifact toneMint
class node_toolchain_registry,node_language_drivers,node_process toneRose
class node_user,node_mln,node_compiler_library,node_toolchain_tools toneIndigo
```

## Components

### CLI workflow

- [Command dispatch](https://github.com/useplx/synapse/blob/main/src/main.cpp): `src/main.cpp`
- [Project commands](https://github.com/useplx/synapse/tree/main/src/cli): `src/cli`
- [Build command](https://github.com/useplx/synapse/blob/main/src/cli/build.cpp): `src/cli/build.cpp`
- [Inspect and graph](https://github.com/useplx/synapse/tree/main/src/cli): `src/cli`

### Project and packages

- [Project manifest](https://github.com/useplx/synapse/blob/main/src/config/project.cpp): `src/config/project.cpp`
- [Typed configuration](https://github.com/useplx/synapse/blob/main/src/config/value.cpp): `src/config/value.cpp`
- [Dependency resolver](https://github.com/useplx/synapse/blob/main/src/package/resolver.cpp): `src/package/resolver.cpp`
- [Dependency lockfile](https://github.com/useplx/synapse/blob/main/src/package/lockfile.cpp): `src/package/lockfile.cpp`
- [Package registry](https://github.com/useplx/synapse/blob/main/src/compiler/package_registry.cpp): `src/compiler/package_registry.cpp`
- [Build plan](https://github.com/useplx/synapse/blob/main/src/cli/compiler_plan.cpp): `src/cli/compiler_plan.cpp`
- [Package composition](https://github.com/useplx/synapse/blob/main/include/syn/package.hpp): `include/syn/package.hpp`
- [Hooks and policies](https://github.com/useplx/synapse/blob/main/include/syn/compiler.hpp): `include/syn/compiler.hpp`

### Compilation and artifacts

- [Compiler API](https://github.com/useplx/synapse/blob/main/src/compiler/compiler_api.cpp): `src/compiler/compiler_api.cpp`
- [Graph compiler](https://github.com/useplx/synapse/blob/main/src/compiler/compiler.cpp): `src/compiler/compiler.cpp`
- [Operation lowering](https://github.com/useplx/synapse/blob/main/include/syn/operations.hpp): `include/syn/operations.hpp`
- [Functional operations](https://github.com/useplx/synapse/tree/main/src/compiler/functional): `src/compiler/functional`
- [Backend selection](https://github.com/useplx/synapse/blob/main/src/compiler/backend.cpp): `src/compiler/backend.cpp`
- [Weight conversion](https://github.com/useplx/synapse/blob/main/src/compiler/weights_pack.cpp): `src/compiler/weights_pack.cpp`
- [Artifact and deployment](https://github.com/useplx/synapse/blob/main/src/compiler/artifact.cpp): `src/compiler/artifact.cpp`

### Toolchains

- [Toolchain selection](https://github.com/useplx/synapse/blob/main/src/toolchain/driver.cpp): `src/toolchain/driver.cpp`
- [Language drivers](https://github.com/useplx/synapse/tree/main/src/toolchain): `src/toolchain`
- [External processes](https://github.com/useplx/synapse/blob/main/src/system/process.cpp): `src/system/process.cpp`

### Other components

- **Project author**
- **MyeLiN SDK/runtime**
- **Compiler library**
- **Language toolchains**
- **MLN artifact**

## Connections

- Project author → Command dispatch: invokes (evidence: `src/main.cpp`)
- Command dispatch → Project commands: dispatches
- Command dispatch → Build command: dispatches
- Command dispatch → Inspect and graph: dispatches
- Project commands → Project manifest: configures
- Build command → Project manifest: loads
- Project manifest → Typed configuration: parses values (evidence: `src/config/project.cpp`)
- Dependency resolver → Project manifest: loads packages (evidence: `src/package/resolver.cpp`)
- Dependency resolver → Dependency lockfile: writes lock
- Dependency resolver → Package registry: resolves packages
- Inspect and graph → Dependency resolver: resolves project
- Inspect and graph → Build plan: prints plan
- Build command → Build plan: prepares plan (evidence: `src/cli/compiler_plan.cpp`)
- Build plan → Dependency resolver: resolves dependencies (evidence: `src/cli/compiler_plan.cpp`)
- Build plan → Toolchain selection: selects toolchains
- Build plan → Package composition: composes packages
- Build command → Compiler API: requests compilation
- Compiler API → Graph compiler: compiles request (evidence: `src/compiler/compiler_api.cpp`)
- Graph compiler → Operation lowering: emits graph
- Operation lowering → Functional operations: dispatches emitters (evidence: `include/syn/operations.hpp`)
- Graph compiler → Hooks and policies: applies configuration (evidence: `include/syn/compiler.hpp`)
- Graph compiler → Backend selection: selects backend
- Graph compiler → Weight conversion: converts weights
- Graph compiler → Artifact and deployment: produces package
- Compiler API → MyeLiN SDK/runtime: uses SDK (evidence: `src/compiler/compiler_api.cpp`)
- Artifact and deployment → MLN artifact: writes artifact
- Toolchain selection → Language drivers: selects driver (evidence: `src/toolchain/driver.cpp`)
- Language drivers → External processes: runs commands (evidence: `src/toolchain/cpp.cpp`)
- External processes → Language toolchains: executes