GraphPath

AI-Powered Developer Skill & Career Graph

GraphPath is the application we will build for the Wexa AI CognoDB take-home assignment.

🎥 Video Demo

Watch the complete GraphPath project demo:

▶️ Watch the GraphPath Demo on YouTube

Application Preview

GraphPath dashboard	Role detail

Learning path	Graph Role Relationships

Problem

A developer often knows their current skills but does not have a clear, relationship-aware path to a target role.

GraphPath models developers, skills, technologies, projects, learning resources, and roles as a graph so users can explore:

• what a target role requires;
• which skills they already have;
• which skills are missing;
• prerequisite chains between skills;
• technologies associated with skills;
• projects that demonstrate skills;
• resources that can help close skill gaps.

Why a graph database?

The core questions are about connections and paths, not isolated records.

Example:

Current Skill
    ↓
Prerequisite
    ↓
Technology
    ↓
Project
    ↓
Demonstrated Skill
    ↓
Target Role

A relational database could represent these entities with join tables, but variable-length prerequisite/path traversal becomes increasingly join-heavy and application-specific. A graph lets the relationships remain first-class.

Core graph model

(User)-[:HAS_SKILL]->(Skill)
(User)-[:TARGETS]->(Role)
(Role)-[:REQUIRES]->(Skill)
(Skill)-[:USED_WITH]->(Technology)
(Skill)-[:PREREQUISITE_OF]->(Skill)
(Project)-[:USES]->(Technology)
(Project)-[:DEMONSTRATES]->(Skill)
(Resource)-[:TEACHES]->(Skill)
(Resource)-[:COVERS]->(Technology)

Main product flows

1. Role Explorer — inspect a role and its connected skills/technologies.
2. Skill Gap Analysis — compare a user's skills with a target role.
3. Learning Path — traverse prerequisite relationships to produce a recommended order.
4. Graph Explorer — inspect connected graph paths.
5. AI Career Assistant — ask natural-language questions grounded in graph results.

AI design

AI is optional to the core product and never becomes the database authority.

User Question
     ↓
Intent Extraction
     ↓
Allowlisted Intent
     ↓
Application Service
     ↓
Parameterized Cypher
     ↓
CognoDB
     ↓
Structured Facts
     ↓
AI Explanation
     ↓
User

The AI must not execute arbitrary generated Cypher.

Repository

app/                 Next.js pages and API routes
components/          UI components
server/              server-only configuration, database, services, AI
cypher/              documented Cypher queries
scripts/             deterministic seed script
tests/               automated tests
docs/                architecture and implementation documentation
.ai/                 AI-agent project context and rules

Assignment requirements mapped to this project

• Graph data model: docs/architecture.md
• Diagram: this README + architecture document
• Realistic seed data: scripts/seed.ts
• Parameterized Cypher: repository layer
• 2+ hop traversal: learning/path query
• Relationally awkward query: skill-gap/prerequisite traversal
• Functional web application: Next.js
• Loading/empty/error states: UI layer
• Database credentials: environment variables
• Graceful database failure: API error layer
• Hosted demo + recording: final deployment phase

Development order

1. Project setup
2. CognoDB health check                         ✓
3. Graph model + seed data
4. Graph verification
5. Core graph queries
6. API/service layer
7. UI
8. Graph experience / visualization
9. UI polish / empty states                       ✓
10. AI assistant
11. Tests
11. Quality / tests
12. Deployment
13. README screenshots + demo recording
14. Interview preparation

Environment

Create .env.local:

COGNODB_URI=bolt+s://<instance-id>.databases.cognodb.cloud
COGNODB_USERNAME=cognodb
COGNODB_PASSWORD=<password>

GROQ_API_KEY=
GROQ_MODEL=openai/gpt-oss-20b

Never commit .env.local.

Local development

npm install
npm run dev

Then open:

http://localhost:3000

Health check:

http://localhost:3000/api/health

Expected:

{
  "data": {
    "status": "ok",
    "database": "connected"
  },
  "error": null
}

Current milestone

Milestones 1–6 — Connectivity, graph foundation, query/API layer, product UI, graph experience, and grounded AI assistant are implemented.

The current milestone is Quality & Submission. The graph explorer now supports drag, pan, zoom, reset, relationship highlighting, a node index, and a selected-node detail panel. See docs/submission-checklist.md and docs/demo-script.md for release verification.

Milestone 2 — Graph model + seed data is implemented in the seed script. Run npm run seed, then npm run verify:graph to verify it against your CognoDB instance.

Do not make AI the source of graph truth. The graph queries and core application must remain functional without AI.

Verification status

Milestones 1–6 are implemented. Milestone 7 is active: automated regression coverage and graph UX polish are in place. Final verification, deployment, screenshots, recording, and GitHub submission remain release tasks.

Run the complete local verification suite:

npm test
npm run typecheck
npm run lint
npm run build
npm run verify:graph

Interview rule

Every implementation decision must be explainable:

• Why graph?
• Why this node?
• Why this relationship?
• Why this query?
• Why this architecture?
• How is Cypher injection prevented?
• What happens if CognoDB is unavailable?
• What happens if the AI provider is unavailable?
• How would the system scale?

Role Detail Screen

Open /roles/role-senior-backend-engineer to inspect a role as a connected graph: required skills, technologies, projects, resources, and the current user's skill coverage. The screen is intentionally powered by CognoDB relationships rather than hard-coded role content.

Learning Path Screen

The completed learning path experience is available at:

/learning-path/role-senior-backend-engineer

It combines the user's HAS_SKILL relationships, role REQUIRES relationships, and PREREQUISITE_OF relationships to present a graph-derived learning sequence.

The UI explicitly distinguishes:

• current skills;
• missing skills;
• prerequisite evidence;
• no-path states;
• full error states.

The graph experience is implemented and available at /graph/role-senior-backend-engineer.

Current implementation milestone

The Graph Experience is now implemented.

Open:

/graph/role-senior-backend-engineer

It is backed by:

GET /api/graph/role/:roleId

The graph screen demonstrates Role → Skill → Technology/Project/Resource and Skill → Prerequisite relationships.

The graph explorer normalizes Neo4j Node objects through their properties field so all returned nodes render correctly. It now also supports node dragging, canvas panning, mouse-wheel zoom, zoom controls, reset view, relationship highlighting, a node-type legend, a grouped node index, and selected-node relationship inspection.

UI Polish

The UI is mobile-first and explicitly distinguishes valid empty states from API/database errors. The graph canvas is intentionally movable rather than forcing the user to read a dense fixed diagram. See docs/ui-polish.md and docs/architecture.md.

AI Assistant

Open /assistant or use the AI panel on the dashboard. The assistant uses Groq through the OpenAI-compatible SDK.

GROQ_API_KEY=<your-groq-key>
GROQ_MODEL=openai/gpt-oss-20b

Provider configuration in TypeScript:

new OpenAI({
  apiKey: process.env.GROQ_API_KEY,
  baseURL: "https://api.groq.com/openai/v1",
});

AI status: /api/ai/status. AI chat: POST /api/ai/chat.

Architecture diagram

See docs/architecture-diagram.md for the Mermaid architecture diagram and AI safety boundary.