# gargi-09/nextnode architecture

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

- Interactive diagram: https://gitdiagram.com/gargi-09/nextnode
- Repository: https://github.com/gargi-09/nextnode

## Overview

Nextnode turns resume and job-description text into graph-backed career analysis: LLM extraction feeds canonical skill resolution and Neo4j, then symbolic reasoning produces fit scores, skill gaps, roadmaps, pivot guidance, and explanations for the web UI. The README also documents direct user/job management, ontology browsing, and graph-health/quota visibility. Some backend and frontend connections are supported by the SOURCE INDEX or README rather than sampled implementation excerpts; those links are cited accordingly.

Main entry points: [`app/services/ingestion.py`](https://github.com/gargi-09/nextnode/blob/main/app/services/ingestion.py) (Text ingestion), [`frontend/src/App.jsx`](https://github.com/gargi-09/nextnode/blob/main/frontend/src/App.jsx) (App navigation), [`app/services/analysis.py`](https://github.com/gargi-09/nextnode/blob/main/app/services/analysis.py) (Analysis service), [`frontend/src/api/client.js`](https://github.com/gargi-09/nextnode/blob/main/frontend/src/api/client.js) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_app_shell["App navigation<br/>[App.jsx]"]
  node_analysis_ui["Analysis views<br/>[Analyze.jsx]"]
  node_management_ui["User and job views<br/>[Users.jsx]"]
  node_ontology_ui["Ontology view<br/>[Ontology.jsx]"]
  node_system_ui["System status view<br/>[System.jsx]"]
  node_api_client["API client<br/>[client.js]"]
end

subgraph group_api["API and services"]
  node_api_routes["Analysis API<br/>[routes.py]"]
  node_user_job_api["User and job API<br/>[users.py]"]
  node_ontology_api["Ontology API<br/>[ontology.py]"]
  node_ingestion["Text ingestion<br/>[ingestion.py]"]
  node_analysis_service["Analysis service<br/>[analysis.py]"]
  node_pivot_service["Pivot service<br/>[pivot.py]"]
  node_management_service["User and job services<br/>[users.py]"]
end

subgraph group_extract["Extraction and graph"]
  node_extractor["Skill extraction<br/>[extractor.py]"]
  node_gemini_client["Gemini client<br/>[llm.py]"]
  node_quota["Quota protection<br/>[quota.py]"]
  node_ontology["Skill ontology<br/>[ontology.py]"]
  node_normalization["Skill normalization<br/>[normalize.py]"]
  node_graph_writer["Graph writer<br/>[writer.py]"]
  node_graph_catalog["Graph catalog<br/>[catalog.py]"]
  node_neo4j[("Neo4j graph<br/>[neo4j.py]")]
end

subgraph group_reason["Career reasoning"]
  node_reasoner["Graph reasoner<br/>[reasoner.py]"]
  node_scoring["Symbolic scoring<br/>[scoring.py]"]
  node_pivot_engine["Pivot analysis<br/>[pivot.py]"]
  node_payloads["Graph payloads<br/>[payloads.py]"]
  node_explainer["Coaching explanation<br/>[explainer.py]"]
end

node_career_user(("Career user"))
node_gemini["Gemini service"]

node_career_user -->|"uses"| node_app_shell
node_app_shell -->|"routes to"| node_analysis_ui
node_app_shell -->|"routes to"| node_management_ui
node_app_shell -->|"routes to"| node_ontology_ui
node_app_shell -->|"routes to"| node_system_ui
node_analysis_ui -.->|"requests analysis"| node_api_client
node_management_ui -->|"requests management"| node_api_client
node_ontology_ui -.->|"loads ontology"| node_api_client
node_system_ui -.->|"loads status"| node_api_client
node_api_client -->|"calls endpoints"| node_api_routes
node_api_routes -->|"dispatches extraction"| node_ingestion
node_api_routes -->|"dispatches analysis"| node_analysis_service
node_api_routes -->|"dispatches pivot"| node_pivot_service
node_user_job_api -->|"dispatches management"| node_management_service
node_ontology_api -->|"serves ontology"| node_ontology
node_ingestion -->|"checks source hash"| node_graph_catalog
node_ingestion -->|"extracts text"| node_extractor
node_ingestion -->|"normalizes skills"| node_normalization
node_ingestion -->|"resolves terms"| node_ontology
node_ingestion -->|"writes records"| node_graph_writer
node_extractor -->|"requests extraction"| node_gemini_client
node_gemini_client -->|"checks budget"| node_quota
node_gemini_client -->|"generates text"| node_gemini
node_graph_catalog -->|"queries graph"| node_neo4j
node_graph_writer -->|"writes graph"| node_neo4j
node_analysis_service -->|"loads graph data"| node_reasoner
node_analysis_service -->|"computes score"| node_scoring
node_analysis_service -->|"builds graph views"| node_payloads
node_analysis_service -->|"generates explanation"| node_explainer
node_reasoner -->|"queries graph"| node_neo4j
node_reasoner -->|"uses rules"| node_scoring
node_pivot_service -->|"extracts target role"| node_extractor
node_pivot_service -->|"computes pivot"| node_pivot_engine
node_pivot_service -->|"uses weights"| node_scoring
node_management_service -.->|"updates graph"| node_graph_writer

click node_app_shell "https://github.com/gargi-09/nextnode/blob/main/frontend/src/App.jsx"
click node_analysis_ui "https://github.com/gargi-09/nextnode/blob/main/frontend/src/pages/Analyze.jsx"
click node_management_ui "https://github.com/gargi-09/nextnode/blob/main/frontend/src/pages/Users.jsx"
click node_ontology_ui "https://github.com/gargi-09/nextnode/blob/main/frontend/src/pages/Ontology.jsx"
click node_system_ui "https://github.com/gargi-09/nextnode/blob/main/frontend/src/pages/System.jsx"
click node_api_client "https://github.com/gargi-09/nextnode/blob/main/frontend/src/api/client.js"
click node_api_routes "https://github.com/gargi-09/nextnode/blob/main/app/api/routes.py"
click node_user_job_api "https://github.com/gargi-09/nextnode/blob/main/app/api/users.py"
click node_ontology_api "https://github.com/gargi-09/nextnode/blob/main/app/api/ontology.py"
click node_ingestion "https://github.com/gargi-09/nextnode/blob/main/app/services/ingestion.py"
click node_analysis_service "https://github.com/gargi-09/nextnode/blob/main/app/services/analysis.py"
click node_pivot_service "https://github.com/gargi-09/nextnode/blob/main/app/services/pivot.py"
click node_management_service "https://github.com/gargi-09/nextnode/blob/main/app/services/users.py"
click node_extractor "https://github.com/gargi-09/nextnode/blob/main/app/extraction/extractor.py"
click node_gemini_client "https://github.com/gargi-09/nextnode/blob/main/app/extraction/llm.py"
click node_quota "https://github.com/gargi-09/nextnode/blob/main/app/extraction/quota.py"
click node_ontology "https://github.com/gargi-09/nextnode/blob/main/app/graph/ontology.py"
click node_normalization "https://github.com/gargi-09/nextnode/blob/main/app/graph/normalize.py"
click node_graph_writer "https://github.com/gargi-09/nextnode/blob/main/app/graph/writer.py"
click node_graph_catalog "https://github.com/gargi-09/nextnode/blob/main/app/graph/catalog.py"
click node_neo4j "https://github.com/gargi-09/nextnode/blob/main/app/db/neo4j.py"
click node_reasoner "https://github.com/gargi-09/nextnode/blob/main/app/graph/reasoner.py"
click node_scoring "https://github.com/gargi-09/nextnode/blob/main/app/graph/scoring.py"
click node_pivot_engine "https://github.com/gargi-09/nextnode/blob/main/app/graph/pivot.py"
click node_payloads "https://github.com/gargi-09/nextnode/blob/main/app/graph/payloads.py"
click node_explainer "https://github.com/gargi-09/nextnode/blob/main/app/extraction/explainer.py"

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_app_shell,node_analysis_ui,node_management_ui,node_ontology_ui,node_system_ui,node_api_client,node_career_user toneBlue
class node_api_routes,node_user_job_api,node_ontology_api,node_ingestion,node_analysis_service,node_pivot_service,node_management_service toneAmber
class node_extractor,node_gemini_client,node_quota,node_ontology,node_normalization,node_graph_writer,node_graph_catalog,node_neo4j toneMint
class node_reasoner,node_scoring,node_pivot_engine,node_payloads,node_explainer toneRose
class node_gemini toneIndigo
```

## Components

### Web application

- [App navigation](https://github.com/gargi-09/nextnode/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Analysis views](https://github.com/gargi-09/nextnode/blob/main/frontend/src/pages/Analyze.jsx): `frontend/src/pages/Analyze.jsx`
- [User and job views](https://github.com/gargi-09/nextnode/blob/main/frontend/src/pages/Users.jsx): `frontend/src/pages/Users.jsx`
- [Ontology view](https://github.com/gargi-09/nextnode/blob/main/frontend/src/pages/Ontology.jsx): `frontend/src/pages/Ontology.jsx`
- [System status view](https://github.com/gargi-09/nextnode/blob/main/frontend/src/pages/System.jsx): `frontend/src/pages/System.jsx`
- [API client](https://github.com/gargi-09/nextnode/blob/main/frontend/src/api/client.js): `frontend/src/api/client.js`

### API and services

- [Analysis API](https://github.com/gargi-09/nextnode/blob/main/app/api/routes.py): `app/api/routes.py`
- [User and job API](https://github.com/gargi-09/nextnode/blob/main/app/api/users.py): `app/api/users.py`
- [Ontology API](https://github.com/gargi-09/nextnode/blob/main/app/api/ontology.py): `app/api/ontology.py`
- [Text ingestion](https://github.com/gargi-09/nextnode/blob/main/app/services/ingestion.py): `app/services/ingestion.py`
- [Analysis service](https://github.com/gargi-09/nextnode/blob/main/app/services/analysis.py): `app/services/analysis.py`
- [Pivot service](https://github.com/gargi-09/nextnode/blob/main/app/services/pivot.py): `app/services/pivot.py`
- [User and job services](https://github.com/gargi-09/nextnode/blob/main/app/services/users.py): `app/services/users.py`

### Extraction and graph

- [Skill extraction](https://github.com/gargi-09/nextnode/blob/main/app/extraction/extractor.py): `app/extraction/extractor.py`
- [Gemini client](https://github.com/gargi-09/nextnode/blob/main/app/extraction/llm.py): `app/extraction/llm.py`
- [Quota protection](https://github.com/gargi-09/nextnode/blob/main/app/extraction/quota.py): `app/extraction/quota.py`
- [Skill ontology](https://github.com/gargi-09/nextnode/blob/main/app/graph/ontology.py): `app/graph/ontology.py`
- [Skill normalization](https://github.com/gargi-09/nextnode/blob/main/app/graph/normalize.py): `app/graph/normalize.py`
- [Graph writer](https://github.com/gargi-09/nextnode/blob/main/app/graph/writer.py): `app/graph/writer.py`
- [Graph catalog](https://github.com/gargi-09/nextnode/blob/main/app/graph/catalog.py): `app/graph/catalog.py`
- [Neo4j graph](https://github.com/gargi-09/nextnode/blob/main/app/db/neo4j.py): `app/db/neo4j.py`

### Career reasoning

- [Graph reasoner](https://github.com/gargi-09/nextnode/blob/main/app/graph/reasoner.py): `app/graph/reasoner.py`
- [Symbolic scoring](https://github.com/gargi-09/nextnode/blob/main/app/graph/scoring.py): `app/graph/scoring.py`
- [Pivot analysis](https://github.com/gargi-09/nextnode/blob/main/app/graph/pivot.py): `app/graph/pivot.py`
- [Graph payloads](https://github.com/gargi-09/nextnode/blob/main/app/graph/payloads.py): `app/graph/payloads.py`
- [Coaching explanation](https://github.com/gargi-09/nextnode/blob/main/app/extraction/explainer.py): `app/extraction/explainer.py`

### Other components

- **Career user**
- **Gemini service**

## Connections

- Career user → App navigation: uses
- App navigation → Analysis views: routes to (evidence: `frontend/src/App.jsx`)
- App navigation → User and job views: routes to (evidence: `frontend/src/App.jsx`)
- App navigation → Ontology view: routes to (evidence: `frontend/src/App.jsx`)
- App navigation → System status view: routes to (evidence: `frontend/src/App.jsx`)
- Analysis views → API client: requests analysis
- User and job views → API client: requests management (evidence: `frontend/src/pages/Users.jsx`)
- Ontology view → API client: loads ontology
- System status view → API client: loads status
- API client → Analysis API: calls endpoints
- Analysis API → Text ingestion: dispatches extraction (evidence: `app/api/routes.py`)
- Analysis API → Analysis service: dispatches analysis (evidence: `app/api/routes.py`)
- Analysis API → Pivot service: dispatches pivot (evidence: `app/api/routes.py`)
- User and job API → User and job services: dispatches management (evidence: `app/api/users.py`)
- Ontology API → Skill ontology: serves ontology (evidence: `app/api/ontology.py`)
- Text ingestion → Graph catalog: checks source hash (evidence: `app/services/ingestion.py`)
- Text ingestion → Skill extraction: extracts text (evidence: `app/services/ingestion.py`)
- Text ingestion → Skill normalization: normalizes skills (evidence: `app/services/ingestion.py`)
- Text ingestion → Skill ontology: resolves terms (evidence: `app/services/ingestion.py`)
- Text ingestion → Graph writer: writes records (evidence: `app/services/ingestion.py`)
- Skill extraction → Gemini client: requests extraction (evidence: `app/extraction/extractor.py`)
- Gemini client → Quota protection: checks budget (evidence: `app/extraction/llm.py`)
- Gemini client → Gemini service: generates text (evidence: `app/extraction/llm.py`)
- Graph catalog → Neo4j graph: queries graph (evidence: `app/graph/catalog.py`)
- Graph writer → Neo4j graph: writes graph (evidence: `app/graph/writer.py`)
- Analysis service → Graph reasoner: loads graph data (evidence: `app/services/analysis.py`)
- Analysis service → Symbolic scoring: computes score (evidence: `app/services/analysis.py`)
- Analysis service → Graph payloads: builds graph views (evidence: `app/services/analysis.py`)
- Analysis service → Coaching explanation: generates explanation (evidence: `app/services/analysis.py`)
- Graph reasoner → Neo4j graph: queries graph (evidence: `app/graph/reasoner.py`)
- Graph reasoner → Symbolic scoring: uses rules (evidence: `app/graph/reasoner.py`)
- Pivot service → Skill extraction: extracts target role (evidence: `app/services/pivot.py`)
- Pivot service → Pivot analysis: computes pivot (evidence: `app/services/pivot.py`)
- Pivot service → Symbolic scoring: uses weights (evidence: `app/services/pivot.py`)
- User and job services → Graph writer: updates graph