How fatiherdgn/meloc-app works
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).