# aryamang1/synapse architecture

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

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

## Overview

1. **Repo purpose and runtime**
   - This is a single-purpose Java project that implements a neural network **from scratch** with no external libraries.
   - The code is organized as a small in-memory training system that learns a function approximation task: **predicting y = x²**.

2. **Top-level architecture**
   - The repository has one application module (`module-info.java`) and one main package (`NeuralNetwork/`).
   - There are no separate services, databases, web APIs, or persistence layers. Everything happens inside the Java process during training and evaluation.

3. **Core domain model**
   - The main architectural building blocks are:
     - `Neuron` for the basic compute unit
     - `Layer` for grouping neurons
     - `NeuralNetwork` for end-to-end orchestration
     - activation function types for non-linear behavior
   - This is a classic layered neural network structure, with data flowing forward and gradients flowing backward.

4. **Activation function boundary**
   - `ActivationFunction.java` defines the shared contract for activation behavior.
   - `ReLU`, `LeakyReLU`, `Sigmoid`, `Tanh`, and `Linear` are concrete activation variants.
   - This is a clean polymorphic boundary: the network can swap activation behavior without changing the rest of the model logic.

5. **Neuron subsystem**
   - `Neuron.java` is the lowest-level learnable unit.
   - A neuron is expected to own its parameters, typically weights and bias, and compute a weighted sum followed by an activation.
   - It also participates in gradient-based updates during backpropagation.

6. **Layer subsystem**
   - `Layer.java` composes multiple neurons into a vectorized stage of the network.
   - Its role is to manage forward propagation across all neurons in the layer and route gradient information backward during training.
   - This is the key structural boundary between single-neuron behavior and network-wide behavior.

7. **Network orchestration**
   - `NeuralNetwork.java` likely coordinates the full training loop:
     - forward pass through all layers
     - loss computation against the target
     - backpropagation of error
     - weight/bias updates
   - This class is the main control plane of the model and likely owns the layer sequence and training hyperparameters.

8. **Training data flow**
   - The README describes a simple supervised learning loop using input-target pairs such as `0.2 -> 0.04`.
   - Data flow is strictly feed-forward during prediction, then reverse-flow during learning:
     - input value enters the first layer
     - output is produced
     - loss is measured
     - gradients are propagated backward
     - parameters are updated
   - The sequence diagram mentioned in the README likely documents this exact flow.

9. **Execution boundary**
   - `NeuralNetworkTester.java` is the entry point used to run training and observe results.
   - It acts as the application harness rather than part of the model itself.
   - The tester likely prints epoch loss and final predictions, serving as the only observable interface to the system.

10. **Build and packaging**
   - The project is plain Java, modularized with `module-info.java`.
   - `package-info.java` suggests the package is documented at the package level, but the architecture remains compact and single-package.
   - There is no build tool visible in the tree, so the repository appears intended to compile directly with the JDK.

11. **Repository documentation assets**
   - `ClassDiagram.png` and `Sequence.png` are architecture documentation artifacts, not runtime dependencies.
   - They reinforce that the system is intentionally simple and centered on the relationship between neuron, layer, network, and training flow.

12. **What is notably absent**
   - There is no indication of convolution, recurrent layers, data loaders, persistence, serialization, concurrency, or external ML frameworks.
   - That means the architecture is best drawn as a small, self-contained learning engine: input sample in, prediction out, gradient updates back in.

13. **Best diagram framing**
   - For an architecture diagram, the main boxes should be:
     - `NeuralNetworkTester` as the runner
     - `NeuralNetwork` as the orchestrator
     - `Layer` as a composite stage
     - `Neuron` as the compute/parameter unit
     - `ActivationFunction` plus its implementations as a strategy family
   - The arrows should show forward inference left-to-right and gradient/update flow right-to-left during training.

Main entry points: [`NeuralNetwork/ActivationFunction.java`](https://github.com/aryamang1/synapse/blob/main/NeuralNetwork/ActivationFunction.java) (Activation API), [`NeuralNetwork/NeuralNetwork.java`](https://github.com/aryamang1/synapse/blob/main/NeuralNetwork/NeuralNetwork.java) (Network), [`NeuralNetwork/Layer.java`](https://github.com/aryamang1/synapse/blob/main/NeuralNetwork/Layer.java) (Layer), [`NeuralNetwork/Neuron.java`](https://github.com/aryamang1/synapse/blob/main/NeuralNetwork/Neuron.java) (Neuron)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_tester["Tester<br/>entrypoint"]
  node_network["Network<br/>orchestrator<br/>[NeuralNetwork.java]"]
  node_layer["Layer<br/>composite<br/>[Layer.java]"]
  node_neuron(("Neuron<br/>unit<br/>[Neuron.java]"))
end

subgraph group_activation["Activation"]
  node_activation_contract["Activation API<br/>strategy-interface"]
  node_relu["ReLU<br/>activation-impl<br/>[ReLU.java]"]
  node_leaky_relu["LeakyReLU<br/>activation-impl<br/>[LeakyReLU.java]"]
  node_sigmoid["Sigmoid<br/>activation-impl<br/>[Sigmoid.java]"]
  node_tanh["Tanh<br/>activation-impl<br/>[Tanh.java]"]
  node_linear["Linear<br/>activation-impl<br/>[Linear.java]"]
end

subgraph group_docs["Docs"]
  node_readme["README<br/>documentation<br/>[README.md]"]
  node_module_info["Module Info<br/>module-boundary<br/>[module-info.java]"]
  node_package_info["Package Info<br/>package-doc<br/>[package-info.java]"]
end

node_tester -->|"runs training"| node_network
node_readme -.->|"describes"| node_tester
node_network -->|"contains"| node_layer
node_layer -->|"contains"| node_neuron
node_neuron -->|"uses"| node_activation_contract
node_activation_contract -.->|"implemented by"| node_relu
node_activation_contract -.->|"implemented by"| node_leaky_relu
node_activation_contract -.->|"implemented by"| node_sigmoid
node_activation_contract -.->|"implemented by"| node_tanh
node_activation_contract -.->|"implemented by"| node_linear
node_network -->|"trains"| node_neuron
node_layer -->|"returns gradients"| node_network
node_neuron -->|"propagates gradients"| node_layer
node_module_info -.->|"packages"| node_network
node_package_info -.->|"documents"| node_network

click node_tester "https://github.com/aryamang1/synapse/blob/main/NeuralNetwork/NeuralNetworkTester.java"
click node_network "https://github.com/aryamang1/synapse/blob/main/NeuralNetwork/NeuralNetwork.java"
click node_layer "https://github.com/aryamang1/synapse/blob/main/NeuralNetwork/Layer.java"
click node_neuron "https://github.com/aryamang1/synapse/blob/main/NeuralNetwork/Neuron.java"
click node_activation_contract "https://github.com/aryamang1/synapse/blob/main/NeuralNetwork/ActivationFunction.java"
click node_relu "https://github.com/aryamang1/synapse/blob/main/NeuralNetwork/ReLU.java"
click node_leaky_relu "https://github.com/aryamang1/synapse/blob/main/NeuralNetwork/LeakyReLU.java"
click node_sigmoid "https://github.com/aryamang1/synapse/blob/main/NeuralNetwork/Sigmoid.java"
click node_tanh "https://github.com/aryamang1/synapse/blob/main/NeuralNetwork/Tanh.java"
click node_linear "https://github.com/aryamang1/synapse/blob/main/NeuralNetwork/Linear.java"
click node_readme "https://github.com/aryamang1/synapse/blob/main/README.md"
click node_module_info "https://github.com/aryamang1/synapse/blob/main/module-info.java"
click node_package_info "https://github.com/aryamang1/synapse/blob/main/NeuralNetwork/package-info.java"

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_tester,node_network,node_layer,node_neuron toneBlue
class node_activation_contract,node_relu,node_leaky_relu,node_sigmoid,node_tanh,node_linear toneAmber
class node_readme,node_module_info,node_package_info toneMint
```

## Components

### Runtime

In-memory training and inference flow

- [Tester](https://github.com/aryamang1/synapse/blob/main/NeuralNetwork/NeuralNetworkTester.java): entrypoint · Runs training and prints results · `NeuralNetwork/NeuralNetworkTester.java`
- [Network](https://github.com/aryamang1/synapse/blob/main/NeuralNetwork/NeuralNetwork.java): orchestrator · Coordinates forward pass, loss, backprop, and updates · `NeuralNetwork/NeuralNetwork.java`
- [Layer](https://github.com/aryamang1/synapse/blob/main/NeuralNetwork/Layer.java): composite · Groups neurons into a stage and routes signals · `NeuralNetwork/Layer.java`
- [Neuron](https://github.com/aryamang1/synapse/blob/main/NeuralNetwork/Neuron.java): unit · Computes weighted sum, activation, and parameter updates · `NeuralNetwork/Neuron.java`

### Activation

Polymorphic nonlinearity boundary

- [Activation API](https://github.com/aryamang1/synapse/blob/main/NeuralNetwork/ActivationFunction.java): strategy-interface · Shared contract for activation behavior · `NeuralNetwork/ActivationFunction.java`
- [ReLU](https://github.com/aryamang1/synapse/blob/main/NeuralNetwork/ReLU.java): activation-impl · Rectified linear activation · `NeuralNetwork/ReLU.java`
- [LeakyReLU](https://github.com/aryamang1/synapse/blob/main/NeuralNetwork/LeakyReLU.java): activation-impl · ReLU variant with small negative slope · `NeuralNetwork/LeakyReLU.java`
- [Sigmoid](https://github.com/aryamang1/synapse/blob/main/NeuralNetwork/Sigmoid.java): activation-impl · Smooth bounded activation · `NeuralNetwork/Sigmoid.java`
- [Tanh](https://github.com/aryamang1/synapse/blob/main/NeuralNetwork/Tanh.java): activation-impl · Centered smooth activation · `NeuralNetwork/Tanh.java`
- [Linear](https://github.com/aryamang1/synapse/blob/main/NeuralNetwork/Linear.java): activation-impl · Pass-through activation · `NeuralNetwork/Linear.java`

### Docs

Repository documentation and guidance

- [README](https://github.com/aryamang1/synapse/blob/main/README.md): documentation · Describes the learning task and flow · `README.md`
- [Module Info](https://github.com/aryamang1/synapse/blob/main/module-info.java): module-boundary · Java module declaration · `module-info.java`
- [Package Info](https://github.com/aryamang1/synapse/blob/main/NeuralNetwork/package-info.java): package-doc · Package-level documentation · `NeuralNetwork/package-info.java`

## Connections

- Tester → Network: runs training · Entry point invokes the model workflow
- README → Tester: describes · Documentation points to the execution harness
- Network → Layer: contains · Network owns an ordered stack of layers
- Layer → Neuron: contains · Layer composes multiple neurons
- Neuron → Activation API: uses · Neuron depends on the activation strategy boundary
- Activation API → ReLU: implemented by · Concrete activation variant
- Activation API → LeakyReLU: implemented by · Concrete activation variant
- Activation API → Sigmoid: implemented by · Concrete activation variant
- Activation API → Tanh: implemented by · Concrete activation variant
- Activation API → Linear: implemented by · Concrete activation variant
- Network → Neuron: trains · Backpropagation ultimately updates neuron parameters
- Layer → Network: returns gradients · Layer propagates error signals back upstream
- Neuron → Layer: propagates gradients · Neuron participates in layer-level backward flow
- Module Info → Network: packages · Module boundary includes the neural network package
- Package Info → Network: documents · Package-level notes for the main model package
