How monetic-labs/cerebro works
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)