# fatiherdgn/meloc-app architecture

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

- Interactive diagram: https://gitdiagram.com/fatiherdgn/meloc-app
- Repository: https://github.com/fatiherdgn/meloc-app

## Overview

##### Project Type and Purpose
- The frontend is built with React/Next.js and D3.js, while the backend is a Node.js/Express monolith that orchestrates calls to OpenAI for embeddings and relation inference, and to Neo4j for persistence and querying.

##### File Structure Analysis
- Top-level directories:
- backend/ – the Express server, controllers, services, data models, utility functions, Docker Compose for Neo4j, and embedding scripts.
- frontend/ – a Next.js application containing UI components, API client code, types, and styling.
- Patterns:
- MVC-style separation in the backend (routes → controllers → services → models).
- Frontend follows Next.js’s App Router structure (app/pages, app/components, app/services).
- Notable config files:
- backend/docker-compose.yml (spins up Neo4j)
- backend/.env.example (OpenAI key, Neo4j credentials)
- frontend/next.config.ts and tsconfig.json

##### Key Components
a. Frontend (React/Next.js)
- Components: GraphVisualizer, ContentRecommendations
- API client: frontend/app/services/api.ts
- D3.js for rendering interactive network graphs
b. Backend (Node.js/Express)
- Entry point: index.js
- Routes: routes/api.js
- Controllers: controllers/graphController.js
- Services:
- openaiService.js → calls OpenAI embeddings & GPT inference
- neo4jService.js → executes Cypher queries against Neo4j
- Utilities: relationUtils.js, similarityUtils.js
- Scripts: scripts/getEmbeddings.js (batch embedding tool)
c. Database
- Neo4j graph database (deployed via Docker Compose)
d. External Services
- OpenAI API (text-embedding-3-small, GPT-4o models)

##### Relationships and Data Flow
1. User interacts with the web UI → triggers a request (e.g., “analyze relationships for concept X”).
2. Frontend API module sends HTTP request to Express endpoint (/api/…).
3. graphController receives request → invokes openaiService to embed the concept(s) and/or infer relationship types.
4. openaiService calls OpenAI API → returns embeddings or inferred labels.
5. similarityUtils calculates semantic similarity scores (optional).
7. Controller formats results → sends JSON back to frontend.
8. Frontend GraphVisualizer component consumes JSON → renders interactive graph via D3.js.

##### Architectural Patterns and Principles
- Separation of concerns:
- API-centric backend: RESTful endpoints decoupled from UI.
- Asynchronous operations: embedding and DB operations return Promises and are non-blocking.
- Proof-of-concept layering: embedding scripts are separate from runtime services.

##### Final Checklist
- Four tiers (Client, API, Database, External).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Tier"
        GraphPage["Graph Page (page.tsx)"]:::frontend
        GV["GraphVisualizer (D3.js)"]:::frontend
        CR["ContentRecommendations"]:::frontend
        APIClient["API Client Module (api.ts)"]:::frontend
        Globals["Global Styles"]:::frontend
    end

    subgraph "API Tier"
        Server["Express Server (index.js)"]:::backend
        Routes["API Routes (api.js)"]:::backend
        Controller["graphController.js"]:::backend
        OpenAIService["openaiService.js"]:::backend
        Neo4jService["neo4jService.js"]:::backend
        RelUtils["relationUtils.js"]:::backend
        SimUtils["similarityUtils.js"]:::backend
    end

    subgraph "Scripts & Models"
        BatchScript["getEmbeddings.js"]:::backend
        ConceptModel["Concept Model (Concept.js)"]:::backend
        RelationModel["ConceptRelation Model (ConceptRelation.js)"]:::backend
        EnvExample[".env.example"]:::backend
        DockerCompose["docker-compose.yml"]:::backend
    end

    subgraph "Database Tier"
        Neo4j["Neo4j Database"]:::database
    end

    subgraph "External Services"
        OpenAI["OpenAI API"]:::external
    end

    %% Client interactions
    GraphPage --> GV
    GraphPage --> CR
    GraphPage --> APIClient
    APIClient -->|"POST /api/graph"| Routes
    Routes --> Controller
    Controller -->|invoke| OpenAIService
    OpenAIService -->|"Embed & Infer"| OpenAI
    OpenAIService --> RelUtils
    RelUtils -->|compute| SimUtils
    Controller -->|call| Neo4jService
    Neo4jService -->|Cypher query| Neo4j
    Controller -->|"JSON response"| APIClient
    APIClient --> GV
    APIClient --> CR

    %% Batch script flow
    BatchScript -.->|"batch embed"| OpenAI
    BatchScript -.->|"batch write"| Neo4j

    %% Docker compose relation
    EnvExample --> DockerCompose
    DockerCompose --> Neo4j

    %% Legend (colors and shapes)
    classDef frontend fill:#ADD8E6,stroke:#000,color:#000;
    classDef backend fill:#90EE90,stroke:#000,color:#000;
    classDef database fill:#FFA500,stroke:#000,color:#000;
    classDef external fill:#DDA0DD,stroke:#000,color:#000;

    %% Click Events
    click GraphVisualizer "https://github.com/fatiherdgn/meloc-app/blob/main/frontend/app/components/GraphVisualizer.tsx"
    click ContentRecommendations "https://github.com/fatiherdgn/meloc-app/blob/main/frontend/app/components/ContentRecommendations.tsx"
    click APIClient "https://github.com/fatiherdgn/meloc-app/blob/main/frontend/app/services/api.ts"
    click GraphPage "https://github.com/fatiherdgn/meloc-app/blob/main/frontend/app/graph/page.tsx"
    click Globals "https://github.com/fatiherdgn/meloc-app/blob/main/frontend/app/globals.css"
    click Server "https://github.com/fatiherdgn/meloc-app/blob/main/backend/index.js"
    click Routes "https://github.com/fatiherdgn/meloc-app/blob/main/backend/routes/api.js"
    click Controller "https://github.com/fatiherdgn/meloc-app/blob/main/backend/controllers/graphController.js"
    click OpenAIService "https://github.com/fatiherdgn/meloc-app/blob/main/backend/services/openaiService.js"
    click Neo4jService "https://github.com/fatiherdgn/meloc-app/blob/main/backend/services/neo4jService.js"
    click RelUtils "https://github.com/fatiherdgn/meloc-app/blob/main/backend/utils/relationUtils.js"
    click SimUtils "https://github.com/fatiherdgn/meloc-app/blob/main/backend/utils/similarityUtils.js"
    click BatchScript "https://github.com/fatiherdgn/meloc-app/blob/main/backend/scripts/getEmbeddings.js"
    click ConceptModel "https://github.com/fatiherdgn/meloc-app/blob/main/backend/models/Concept.js"
    click RelationModel "https://github.com/fatiherdgn/meloc-app/blob/main/backend/models/ConceptRelation.js"
    click DockerCompose "https://github.com/fatiherdgn/meloc-app/blob/main/backend/docker-compose.yml"
    click EnvExample "https://github.com/fatiherdgn/meloc-app/blob/main/backend/.env.example"
```
