# adilshamim8/neurobridge architecture

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

- Interactive diagram: https://gitdiagram.com/adilshamim8/neurobridge
- Repository: https://github.com/adilshamim8/neurobridge

## Overview

1. **Repository shape**
   - This is a multi-package product repo, not a single app. It contains a Python library, a Python FastAPI service, a JavaScript/TypeScript SDK, a marketing/docs website, a demo app, ML assets, and a test/benchmark suite.
   - The architectural center is the Python `neurobridge` package, with the other surfaces wrapping or re-exposing its behavior.

2. **Primary runtime boundary: the Python core library**
   - `neurobridge/core` is the main adaptation pipeline.
   - The core flow is: input from an LLM or text source → profile selection/persistence → transform pipeline → format adaptation → adapted output.
   - This is the boundary that turns raw model output into cognitive-accessibility-specific output.

3. **Core subsystems inside the Python package**
   - `bridge.py` coordinates the end-to-end wrapper behavior.
   - `profile.py`, `quiz.py`, and `validators.py` handle profile definitions, assessment, and input validation.
   - `transform.py` and `format_adapter.py` are the main content-processing layers.
   - `memory.py` stores user preference deltas and profile-related state across sessions.
   - `exceptions.py` provides a shared error boundary for the package.

4. **How data moves through the product**
   - The application supplies an LLM client or raw text.
   - NeuroBridge determines a cognitive profile either from explicit selection, quiz results, or remembered preferences.
   - Text is then rewritten by a sequence of transforms tailored to that profile.
   - The transformed content is rendered through a format adapter for markdown, HTML, JSON, plain text, or TTS-oriented output.

5. **Profile and memory layer**
   - The profile system is not just a static enum; it supports a quiz-driven profile selection flow and custom profiles.
   - Memory is a separate concern from transformation: it tracks user edits and long-lived preferences so the system can adapt over time.
   - The memory backend is abstracted, with SQLite as the default and Redis/custom backends supported by configuration.

6. **LLM integration adapters**
   - `neurobridge/integrations` contains provider-specific wrappers for OpenAI, Anthropic, Hugging Face, and LangChain.
   - These adapters exist to keep the core transform pipeline provider-agnostic while still fitting each ecosystem’s calling conventions.
   - The important architectural boundary is that providers remain upstream data sources; NeuroBridge intercepts and adapts their outputs without owning the model inference path.

7. **REST API server as a language-agnostic entry point**
   - `neurobridge/server` exposes the core capabilities over FastAPI.
   - Routers split the API by concern: adapt, quiz, profiles, and health.
   - This service is the integration boundary for non-Python clients and for deployments that want a centralized adaptation layer.

8. **ML-based detection subsystem**
   - `neurobridge/ml` is a separate subsystem for profile detection/training, with feature extraction, training, tracking, and detector code.
   - The presence of `model.pkl` indicates a prebuilt model artifact used at runtime, while `trainer.py` and `generator.py` support offline model generation.
   - This ML path complements the quiz/manual profile flow and feeds the same profile-selection boundary.

9. **JavaScript/TypeScript SDK**
   - `packages/neurobridge-js` mirrors the product concept for JS consumers.
   - It includes bridge logic, integrations, memory abstractions, and transform utilities similar to the Python stack, but packaged for Node/browser environments.
   - This is a separate distribution boundary, useful when the host app is JavaScript-native and does not want Python in-process.

10. **Website and API routes**
    - `website` is a Next.js application that serves docs, marketing pages, playgrounds, stats, and user-facing flows like quiz, shared outputs, and newsletter signup.
    - Its API routes handle product-adjacent concerns such as adapt requests, feedback, GitHub stars, stats, newsletter subscription, and Open Graph generation.
    - These routes are distinct from the core NeuroBridge API server; they support the public site and community funnel rather than the library itself.

11. **Demo, examples, and benchmarks**
    - `demo` is a small interactive showcase app, likely used to demonstrate transformations on sample “before/after” text.
    - `examples` provides integration-oriented usage snippets for Python consumers.
    - `benchmarks` measures API, pipeline, memory, and transform performance, indicating the main nonfunctional concern is transform latency overhead on LLM output.

12. **Test and quality architecture**
    - The tests are broad and subsystem-aligned: core bridge, memory, transforms, profiles, quiz, server APIs, integrations, streaming, ML, and performance.
    - `tests/cassettes` suggests VCR-style recorded integration tests for external provider calls.
    - CI workflows plus release docs indicate a strong gated release process around correctness, compatibility, and packaging.

13. **External dependencies that shape the architecture**
    - The core product depends on third-party LLM providers and optional backends like Redis.
    - The server side uses FastAPI; the website uses Next.js/Vercel-style deployment; the JS SDK is built with a bundler for npm distribution.
    - These aren’t incidental—they define the main system boundaries: library, API service, frontend site, and SDK distributions.

14. **Overall diagram takeaway**
    - The central diagram should show a shared “adaptation engine” in the Python core, fed by LLM outputs or raw text, with profile selection/memory/ML influencing transforms and formatting.
    - Around that core are three major access paths: in-process Python integration, REST API server, and JS SDK.
    - The website, demo, and docs sit outside the core product path as presentation and onboarding surfaces, while tests/benchmarks validate the behavior of every subsystem.

Main entry points: [`neurobridge/core/bridge.py`](https://github.com/adilshamim8/neurobridge/blob/main/neurobridge/core/bridge.py) (Bridge), [`tests`](https://github.com/adilshamim8/neurobridge/tree/main/tests) (Tests), [`neurobridge/server/routers`](https://github.com/adilshamim8/neurobridge/tree/main/neurobridge/server/routers) (API routes), [`neurobridge/core/profile.py`](https://github.com/adilshamim8/neurobridge/blob/main/neurobridge/core/profile.py) (Profiles)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_python_core["Python core"]
  node_bridge["Bridge<br/>orchestrator<br/>[bridge.py]"]
  node_profile["Profiles<br/>selection<br/>[profile.py]"]
  node_quiz["Quiz<br/>assessment<br/>[quiz.py]"]
  node_validators["Validators<br/>input checks<br/>[validators.py]"]
  node_memory[("Memory<br/>state store<br/>[memory.py]")]
  node_transform["Transforms<br/>rewrite pipeline<br/>[transform.py]"]
  node_format_adapter["Format adapter<br/>rendering<br/>[format_adapter.py]"]
  node_exceptions{{"Errors<br/>error boundary<br/>[exceptions.py]"}}
end

subgraph group_python_surfaces["Python surfaces"]
  node_integrations["LLM adapters<br/>provider wrappers"]
  node_server_app["FastAPI server<br/>api service<br/>[app.py]"]
  node_server_routers["API routes<br/>routing layer"]
  node_ml_detector["Detector<br/>profile inference<br/>[detector.py]"]
  node_ml_trainer["Trainer<br/>offline training<br/>[trainer.py]"]
  node_ml_model[("Model artifact<br/>runtime model<br/>[model.pkl]")]
end

subgraph group_js_sdk["JS SDK"]
  node_js_bridge["JS bridge<br/>orchestrator<br/>[bridge.ts]"]
  node_js_integrations["JS adapters<br/>provider wrappers"]
  node_js_memory[("JS memory<br/>state store")]
  node_js_transform["JS transforms<br/>rewrite pipeline"]
end

subgraph group_product_ui["Website and demo"]
  node_website_app["Website app<br/>Next.js site"]
  node_website_api["Site API<br/>route handlers"]
  node_demo_app["Demo app<br/>showcase<br/>[app.py]"]
end

subgraph group_quality["Quality and validation"]
  node_benchmarks["Benchmarks<br/>performance suite"]
  node_tests["Tests<br/>validation suite"]
end

node_bridge -->|"validates"| node_validators
node_bridge -->|"selects"| node_profile
node_bridge -->|"reads/writes"| node_memory
node_bridge -->|"applies"| node_transform
node_bridge -->|"renders"| node_format_adapter
node_quiz -->|"infers"| node_profile
node_memory -.->|"biases"| node_profile
node_transform -->|"passes to"| node_format_adapter
node_exceptions -.->|"shared by"| node_bridge
node_integrations -->|"feeds input"| node_bridge
node_integrations -.->|"adapts"| node_validators
node_server_app -->|"mounts"| node_server_routers
node_server_routers -->|"calls"| node_bridge
node_server_routers -->|"calls"| node_quiz
node_server_routers -->|"calls"| node_profile
node_server_routers -->|"calls"| node_ml_detector
node_ml_detector -->|"loads"| node_ml_model
node_ml_trainer -->|"produces"| node_ml_model
node_ml_trainer -.->|"trains for"| node_profile
node_js_bridge -->|"applies"| node_js_transform
node_js_bridge -->|"reads/writes"| node_js_memory
node_js_bridge -->|"wraps"| node_js_integrations
node_website_app -->|"uses"| node_website_api
node_website_api -.->|"adapts via"| node_bridge
node_demo_app -->|"demonstrates"| node_bridge
node_benchmarks -->|"measures"| node_bridge
node_benchmarks -.->|"measures"| node_memory
node_tests -->|"verifies"| node_bridge
node_tests -->|"verifies"| node_server_app
node_tests -->|"verifies"| node_integrations
node_tests -->|"verifies"| node_ml_detector
node_tests -.->|"verifies"| node_js_bridge

click node_bridge "https://github.com/adilshamim8/neurobridge/blob/main/neurobridge/core/bridge.py"
click node_profile "https://github.com/adilshamim8/neurobridge/blob/main/neurobridge/core/profile.py"
click node_quiz "https://github.com/adilshamim8/neurobridge/blob/main/neurobridge/core/quiz.py"
click node_validators "https://github.com/adilshamim8/neurobridge/blob/main/neurobridge/core/validators.py"
click node_memory "https://github.com/adilshamim8/neurobridge/blob/main/neurobridge/core/memory.py"
click node_transform "https://github.com/adilshamim8/neurobridge/blob/main/neurobridge/core/transform.py"
click node_format_adapter "https://github.com/adilshamim8/neurobridge/blob/main/neurobridge/core/format_adapter.py"
click node_exceptions "https://github.com/adilshamim8/neurobridge/blob/main/neurobridge/exceptions.py"
click node_integrations "https://github.com/adilshamim8/neurobridge/tree/main/neurobridge/integrations"
click node_server_app "https://github.com/adilshamim8/neurobridge/blob/main/neurobridge/server/app.py"
click node_server_routers "https://github.com/adilshamim8/neurobridge/tree/main/neurobridge/server/routers"
click node_ml_detector "https://github.com/adilshamim8/neurobridge/blob/main/neurobridge/ml/detector.py"
click node_ml_trainer "https://github.com/adilshamim8/neurobridge/blob/main/neurobridge/ml/trainer.py"
click node_ml_model "https://github.com/adilshamim8/neurobridge/blob/main/neurobridge/ml/model.pkl"
click node_js_bridge "https://github.com/adilshamim8/neurobridge/blob/main/packages/neurobridge-js/src/bridge.ts"
click node_js_integrations "https://github.com/adilshamim8/neurobridge/tree/main/packages/neurobridge-js/src/integrations"
click node_js_memory "https://github.com/adilshamim8/neurobridge/tree/main/packages/neurobridge-js/src/memory"
click node_js_transform "https://github.com/adilshamim8/neurobridge/tree/main/packages/neurobridge-js/src/transform"
click node_website_app "https://github.com/adilshamim8/neurobridge/tree/main/website/app"
click node_website_api "https://github.com/adilshamim8/neurobridge/tree/main/website/app/api"
click node_demo_app "https://github.com/adilshamim8/neurobridge/blob/main/demo/app.py"
click node_benchmarks "https://github.com/adilshamim8/neurobridge/tree/main/benchmarks"
click node_tests "https://github.com/adilshamim8/neurobridge/tree/main/tests"

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_bridge,node_profile,node_quiz,node_validators,node_memory,node_transform,node_format_adapter,node_exceptions toneBlue
class node_integrations,node_server_app,node_server_routers,node_ml_detector,node_ml_trainer,node_ml_model toneAmber
class node_js_bridge,node_js_integrations,node_js_memory,node_js_transform toneMint
class node_website_app,node_website_api,node_demo_app toneRose
class node_benchmarks,node_tests toneIndigo
```

## Components

### Python core

Primary adaptation engine and shared runtime boundary.

- [Bridge](https://github.com/adilshamim8/neurobridge/blob/main/neurobridge/core/bridge.py): orchestrator · Coordinates end-to-end adaptation flow from input to output. · `neurobridge/core/bridge.py`
- [Profiles](https://github.com/adilshamim8/neurobridge/blob/main/neurobridge/core/profile.py): selection · Defines cognitive profiles and custom profile selection rules. · `neurobridge/core/profile.py`
- [Quiz](https://github.com/adilshamim8/neurobridge/blob/main/neurobridge/core/quiz.py): assessment · Collects answers to infer or refine the best-fit profile. · `neurobridge/core/quiz.py`
- [Validators](https://github.com/adilshamim8/neurobridge/blob/main/neurobridge/core/validators.py): input checks · Validates inputs and guards the core boundary. · `neurobridge/core/validators.py`
- [Memory](https://github.com/adilshamim8/neurobridge/blob/main/neurobridge/core/memory.py): state store · Persists user preference deltas and profile-related state across sessions. · `neurobridge/core/memory.py`
- [Transforms](https://github.com/adilshamim8/neurobridge/blob/main/neurobridge/core/transform.py): rewrite pipeline · Applies profile-specific content rewrites and normalization steps. · `neurobridge/core/transform.py`
- [Format adapter](https://github.com/adilshamim8/neurobridge/blob/main/neurobridge/core/format_adapter.py): rendering · Converts adapted content into markdown, HTML, JSON, plain text, or TTS-oriented output. · `neurobridge/core/format_adapter.py`
- [Errors](https://github.com/adilshamim8/neurobridge/blob/main/neurobridge/exceptions.py): error boundary · Shared exception types for package-wide failure handling. · `neurobridge/exceptions.py`

### Python surfaces

Entry points that expose the core library to users and applications.

- [LLM adapters](https://github.com/adilshamim8/neurobridge/tree/main/neurobridge/integrations): provider wrappers · Provider-specific wrappers that keep the core pipeline upstream-provider agnostic. · `neurobridge/integrations`
- [FastAPI server](https://github.com/adilshamim8/neurobridge/blob/main/neurobridge/server/app.py): api service · Language-agnostic REST entry point for adaptation, quiz, profiles, and health. · `neurobridge/server/app.py`
- [API routes](https://github.com/adilshamim8/neurobridge/tree/main/neurobridge/server/routers): routing layer · Splits the service into adapt, quiz, profiles, and health routers. · `neurobridge/server/routers`
- [Detector](https://github.com/adilshamim8/neurobridge/blob/main/neurobridge/ml/detector.py): profile inference · Uses the runtime model to infer profiles from text features. · `neurobridge/ml/detector.py`
- [Trainer](https://github.com/adilshamim8/neurobridge/blob/main/neurobridge/ml/trainer.py): offline training · Builds and updates the profile detection model from synthetic or tracked data. · `neurobridge/ml/trainer.py`
- [Model artifact](https://github.com/adilshamim8/neurobridge/blob/main/neurobridge/ml/model.pkl): runtime model · Prebuilt model artifact used by the detection path at runtime. · `neurobridge/ml/model.pkl`

### JS SDK

TypeScript distribution for Node and browser consumers.

- [JS bridge](https://github.com/adilshamim8/neurobridge/blob/main/packages/neurobridge-js/src/bridge.ts): orchestrator · TypeScript bridge that mirrors the Python adaptation flow for JS consumers. · `packages/neurobridge-js/src/bridge.ts`
- [JS adapters](https://github.com/adilshamim8/neurobridge/tree/main/packages/neurobridge-js/src/integrations): provider wrappers · Provider wrappers for OpenAI, Anthropic, and Vercel AI ecosystems. · `packages/neurobridge-js/src/integrations`
- [JS memory](https://github.com/adilshamim8/neurobridge/tree/main/packages/neurobridge-js/src/memory): state store · Browser and Node memory abstractions for persisting preferences. · `packages/neurobridge-js/src/memory`
- [JS transforms](https://github.com/adilshamim8/neurobridge/tree/main/packages/neurobridge-js/src/transform): rewrite pipeline · TypeScript transformation utilities that mirror the core rewrite stages. · `packages/neurobridge-js/src/transform`

### Website and demo

Public site, docs, and showcase surfaces around the product.

- [Website app](https://github.com/adilshamim8/neurobridge/tree/main/website/app): Next.js site · Docs, marketing pages, playgrounds, quiz, shared outputs, and stats views. · `website/app`
- [Site API](https://github.com/adilshamim8/neurobridge/tree/main/website/app/api): route handlers · Public-site endpoints for adapt, feedback, stars, stats, newsletter, quiz, and OG generation. · `website/app/api`
- [Demo app](https://github.com/adilshamim8/neurobridge/blob/main/demo/app.py): showcase · Interactive example app for before-and-after transformation demos. · `demo/app.py`

### Quality and validation

Benchmarks and tests that validate the core behavior and integrations.

- [Benchmarks](https://github.com/adilshamim8/neurobridge/tree/main/benchmarks): performance suite · Measures API, pipeline, memory, and transform performance. · `benchmarks`
- [Tests](https://github.com/adilshamim8/neurobridge/tree/main/tests): validation suite · Covers core behavior, integrations, server APIs, ML, streaming, and performance. · `tests`

## Connections

- Bridge → Validators: validates · Checks incoming text, requests, and configuration before adaptation.
- Bridge → Profiles: selects · Chooses an explicit, quiz-derived, remembered, or detected profile.
- Bridge → Memory: reads/writes · Loads remembered preferences and persists preference deltas.
- Bridge → Transforms: applies · Runs the profile-specific rewrite pipeline over the content.
- Bridge → Format adapter: renders · Exports the adapted result in the requested output format.
- Quiz → Profiles: infers · Maps assessment responses to a usable profile selection.
- Memory → Profiles: biases · Long-lived preferences influence future profile choice.
- Transforms → Format adapter: passes to · Hands structured adapted content to the final renderer.
- Errors → Bridge: shared by · Provides common error types for the core orchestration layer.
- LLM adapters → Bridge: feeds input · Wraps provider outputs and sends them into the adaptation pipeline.
- LLM adapters → Validators: adapts · Normalizes provider-specific payloads before core validation.
- FastAPI server → API routes: mounts · Composes the REST service from concern-specific routers.
- API routes → Bridge: calls · Exposes core adaptation through the API boundary.
- API routes → Quiz: calls · Supports quiz-driven profile selection over HTTP.
- API routes → Profiles: calls · Serves profile inspection and selection endpoints.
- API routes → Detector: calls · Uses ML inference when profile detection is enabled.
- Detector → Model artifact: loads · Reads the prebuilt classifier artifact for runtime detection.
- Trainer → Model artifact: produces · Creates or refreshes the detector artifact offline.
- Trainer → Profiles: trains for · Optimizes detection around the same profile boundary used by the core.
- JS bridge → JS transforms: applies · Runs the JS-side adaptation steps over input text.
- JS bridge → JS memory: reads/writes · Persists browser or Node preferences for future sessions.
- JS bridge → JS adapters: wraps · Integrates with provider SDKs while keeping the product flow consistent.
- Website app → Site API: uses · Frontend pages call site-specific API endpoints for quiz, stats, and sharing.
- Site API → Bridge: adapts via · Public-site adapt endpoints delegate to the core engine.
- Demo app → Bridge: demonstrates · Showcases the adaptation flow on sample before/after content.
- Benchmarks → Bridge: measures · Profiles the end-to-end pipeline latency and overhead.
- Benchmarks → Memory: measures · Tracks persistence and lookup costs of the memory layer.
- Tests → Bridge: verifies · Covers the core orchestration and rewrite behavior.
- Tests → FastAPI server: verifies · Exercises the REST API contract and service behavior.
- Tests → LLM adapters: verifies · Uses recorded provider interactions for integration coverage.
- Tests → Detector: verifies · Checks inference and feature extraction behavior.
- Tests → JS bridge: verifies · Covers the SDK surface and distribution behavior.