# monetic-labs/cerebro architecture

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

- Interactive diagram: https://gitdiagram.com/monetic-labs/cerebro
- Repository: https://github.com/monetic-labs/cerebro

## Overview

##### Project type and purpose
- This is a full-stack, React/Next.js web application (“Cerebro”) for project management.
- It provides an interactive graph-based UI, real-time updates, and a Neo4j graph database for persistence.

##### File structure
- Frontend (Next.js) lives under src/app, src/components, src/hooks, src/contexts, src/providers.
- API layer is implemented via Next.js API routes in src/app/api/graph/**.
- Business logic (“services”) resides in src/services/graph, organized by node type (feature, meta, team, etc.), with a shared Neo4j provider.
- Utility functions under src/utils; type definitions under src/types.
- Configuration & deployment: docker-compose.yml (Neo4j), next.config.ts, vercel.json.

##### README for additional insights
- Core systems:
- Node Data Manifest System (publish/subscribe, type-safe data manifests)
- Team Resource Observer (centralized resource allocation, real-time consistency)
- Tech stack: Next.js, React, TypeScript, Neo4j, Docker, Vercel.

a. Main components
- Frontend Client
- Next.js pages / React components (Graph canvas, Node UIs, Allocation panels)
- React Contexts & Hooks (state management, subscriptions to manifests)
- Backend / BFF (Next.js API Layer)
- API Routes (src/app/api/graph/…/route.ts)
- Graph-API client & controllers
- Service Layer
- Node Manifests & Services (feature.service.ts, team.service.ts, etc.)
- Observer / Subscription Engine
- Data Persistence
- Neo4j Graph Database (Docker container)
- Neo4j Provider & Connector (neo4j.service.ts)
- External & Infrastructure
- Docker / Neo4j
- Vercel (hosting)
- GitHub (CI/CD)

b. Relationships & interactions
- User → Frontend Client (HTTP/Browser events)
- Frontend → Backend API (REST/JSON over HTTP)
- API Layer → Service Layer (internal function calls)
- Service Layer → Neo4j (Cypher queries via neo4j.provider)
- Service Layer ↔ Observer System (publish/subscribe events)
- Observer System → Frontend (push updates via websockets/SSE or polling hooks)

c. Architectural patterns & design principles
- BFF (Backend-for-Frontend): Next.js API routes tailor data to UI needs.
- Hexagonal / Clean Architecture: separation between API adapters, domain services, and infrastructure (Neo4j).
- Observer / Pub-Sub: Node Data Manifest System for data dependencies & real-time sync.
- Domain-Driven Organization: one folder per node type with manifest, service, transform, types.
- Type Safety: TypeScript contracts across layers.

d. Key technologies & frameworks
- Next.js (App Router, API routes)
- React (custom hooks, contexts)
- Neo4j (graph database)
- Docker Compose (spin up Neo4j)
- TypeScript for types across UI, services, DB layer

##### Detailed capture of essential elements
- Frontend: highlight NodeManifestVisualizer, resource allocation components, React Contexts
- API: include one sample route (e.g., /api/graph/feature/[id]) to represent pattern
- Services: show the manifest → service → transform flow per node type
- Database: label Neo4j container, config (bolt URL)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend Client"
        direction TB
        Pages["Pages (src/app)"]:::frontend
        Components["Components (src/components)"]:::frontend
        Hooks["Hooks (src/hooks)"]:::frontend
        Contexts["Contexts (src/contexts)"]:::frontend
        Providers["Providers (src/providers)"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend / BFF"
        direction TB
        API_Routes["Next.js API Routes (src/app/api/graph)"]:::api
        GraphClient["Graph API Client & Controllers"]:::service
    end

    %% Service Layer
    subgraph "Service Layer"
        direction TB
        FeatureServices["Feature Services (src/services/graph/feature)"]:::service
        MetaServices["Meta Services (src/services/graph/meta)"]:::service
        MilestoneServices["Milestone Services (src/services/graph/milestone)"]:::service
        OptionServices["Option Services (src/services/graph/option)"]:::service
        TeamServices["Team Services (src/services/graph/team)"]:::service
        Observer["Observer Engine (src/services/graph/observer)"]:::observer
        Neo4jProvider["Neo4j Provider & Connector"]:::service
        Utils["Utilities & Types (src/utils & src/types)"]:::service
    end

    %% Database & Infrastructure
    Database["Neo4j Graph Database"]:::db
    Docker["Docker / Neo4j"]:::external
    Vercel["Vercel Hosting"]:::external
    GitHub["GitHub CI/CD"]:::external

    %% Data Flows
    User(["User"]):::external -->|"interacts with"| Pages
    Pages -->|"renders UI and calls"| API_Routes
    API_Routes -->|"calls"| GraphClient
    GraphClient -->|"invokes"| FeatureServices
    GraphClient -->|"invokes"| MetaServices
    GraphClient -->|"invokes"| MilestoneServices
    GraphClient -->|"invokes"| OptionServices
    GraphClient -->|"invokes"| TeamServices
    FeatureServices -->|"queries"| Neo4jProvider
    MetaServices -->|"queries"| Neo4jProvider
    MilestoneServices -->|"queries"| Neo4jProvider
    OptionServices -->|"queries"| Neo4jProvider
    TeamServices -->|"queries"| Neo4jProvider
    Neo4jProvider -->|"executes Cypher"| Database
    Observer -->|"publishes updates to"| Hooks
    Observer -->|"subscribes to events from"| FeatureServices
    Observer -->|"subscribes to events from"| MetaServices
    Observer -->|"subscribes to events from"| MilestoneServices
    Observer -->|"subscribes to events from"| OptionServices
    Observer -->|"subscribes to events from"| TeamServices
    Providers -->|"wraps"| Components
    Contexts -->|"provides state to"| Components
    Components -->|"uses"| Hooks

    Docker -->|"hosts"| Database
    Vercel -->|"deploys"| API_Routes
    GitHub -->|"CI/CD pipeline"| Vercel

    %% Click Events
    click Pages "https://github.com/monetic-labs/cerebro/tree/main/src/app"
    click Components "https://github.com/monetic-labs/cerebro/tree/main/src/components"
    click Hooks "https://github.com/monetic-labs/cerebro/tree/main/src/hooks"
    click Contexts "https://github.com/monetic-labs/cerebro/tree/main/src/contexts"
    click Providers "https://github.com/monetic-labs/cerebro/blob/main/src/providers/index.tsx"
    click API_Routes "https://github.com/monetic-labs/cerebro/blob/main/src/app/api/graph/feature/[id]/route.ts"
    click GraphClient "https://github.com/monetic-labs/cerebro/blob/main/src/services/api/graph-api.client.ts"
    click FeatureServices "https://github.com/monetic-labs/cerebro/tree/main/src/services/graph/feature"
    click MetaServices "https://github.com/monetic-labs/cerebro/tree/main/src/services/graph/meta"
    click MilestoneServices "https://github.com/monetic-labs/cerebro/tree/main/src/services/graph/milestone"
    click OptionServices "https://github.com/monetic-labs/cerebro/tree/main/src/services/graph/option"
    click TeamServices "https://github.com/monetic-labs/cerebro/tree/main/src/services/graph/team"
    click Observer "https://github.com/monetic-labs/cerebro/tree/main/src/services/graph/observer"
    click Neo4jProvider "https://github.com/monetic-labs/cerebro/blob/main/src/services/graph/neo4j/neo4j.provider.ts"
    click Utils "https://github.com/monetic-labs/cerebro/tree/main/src/utils"
    click Database "https://github.com/monetic-labs/cerebro/blob/main/docker-compose.yml"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#003366,stroke-width:1px
    classDef api fill:#DFFFE0,stroke:#336600,stroke-width:1px
    classDef service fill:#E0FFE0,stroke:#339933,stroke-width:1px
    classDef db fill:#FFF2B2,stroke:#996600,stroke-width:1px
    classDef observer fill:#FFE5CC,stroke:#CC7A00,stroke-width:1px
    classDef external fill:#E8E8E8,stroke:#666666,stroke-width:1px
```
