AfroGraph — Afrobeats Cultural & Collaboration Knowledge Graph

Wexa AI Take-Home Assignment — Graph Database Application
Backed by CognoDB Cloud (openCypher over Bolt protocol) using the official neo4j-driver.

---

1. Overview & Cultural Roots

AfroGraph is an interactive knowledge graph exploring the talent incubators (YBNL, Mavin, Starboy), sound architect producers, and multi-generational sample lineages powering the global Afrobeats phenomenon.

• Inspiration & Lineage: AfroGraph natively expands on OlamideVerse (GitHub), transforming an editorial cultural archive into a living, multi-label, multi-producer graph ecosystem.
• Live Hosted Demo: afrograph.vercel.app
• GitHub Repository: github.com/ajibolagenius/afrograph

---

2. Why a Graph Database?

Music ecosystems are deeply interconnected networks. Relational databases require complex joins and recursive CTEs that struggle with variable-depth relationships:

Capability	Relational (SQL)	Graph (CognoDB / openCypher)
Shortest Path (Degrees of Separation)	Expensive recursive CTEs (WITH RECURSIVE), cycle prevention logic, full table scans.	Native shortestPath() traversal via pointer-chasing in constant hop time.
Incubation Trees & Blast Radius	Joining 5+ normalized tables with composite GROUP BY and LEFT JOINs.	Single pattern match: (:RecordLabel)<-[:SIGNED_TO]-(:Artist)-[:MENTORED]->(:Artist).
Multi-Hop Sample Lineage	Hierarchical parent-child lookups across heterogeneous entities are slow.	Seamless variable-length jump: (:Sample)<-[:SAMPLED*1..4]-(:Track)<-[:RELEASED]-(:Artist).
Circular Cliques (Triangles)	3-way self-joins on dense tables with expensive inequality filters.	Expressive declarative pattern: (a)-[:COLLABORATED_WITH]->(b)-[:COLLABORATED_WITH]->(c)-[:COLLABORATED_WITH]->(a).

---

3. Graph Data Model

Entities & Relationships

• Nodes: :Artist, :Producer, :RecordLabel, :Track, :Sample
• Edges: [:FOUNDED], [:SIGNED_TO], [:MENTORED], [:RELEASED], [:FEATURED_ON], [:PRODUCED], [:SAMPLED], [:INFLUENCED_BY], [:COLLABORATED_WITH]

graph LR
    Artist["🎨 :Artist"] -->|"FOUNDED / SIGNED_TO"| Label["🏛️ :RecordLabel"]
    Artist -->|"MENTORED / COLLABORATED_WITH"| Artist
    Artist -->|"RELEASED / FEATURED_ON"| Track["🎵 :Track"]
    Producer["🎧 :Producer"] -->|"PRODUCED"| Track
    Track -->|"SAMPLED / INFLUENCED_BY"| Sample["📻 :Sample"]

Loading

---

4. Key openCypher Queries

1. Degrees of Separation (Shortest Path)

MATCH (start:Artist {id: $startId}), (target:Artist {id: $targetId})
MATCH path = shortestPath((start)-[:COLLABORATED_WITH|FEATURED_ON|RELEASED|PRODUCED|MENTORED*1..8]-(target))
RETURN path, nodes(path) AS nodes, relationships(path) AS relationships, length(path) AS length

2. Label Talent Incubation & Blast Radius

MATCH (label:RecordLabel {id: $labelId})
OPTIONAL MATCH (label)<-[:FOUNDED]-(founder:Artist)
OPTIONAL MATCH (artist:Artist)-[s:SIGNED_TO]->(label)
OPTIONAL MATCH (artist)-[m:MENTORED]->(mentee:Artist)
OPTIONAL MATCH (artist)-[rel:RELEASED]->(t:Track)
OPTIONAL MATCH (guest:Artist)-[f:FEATURED_ON]->(t)
RETURN label, founder, collect(DISTINCT artist) AS artists, collect(DISTINCT mentee) AS mentees, collect(DISTINCT t) AS tracks

3. Musical DNA & Sample Lineage Chain

MATCH (sample:Sample {id: $sampleId})
OPTIONAL MATCH (t:Track)-[s:SAMPLED|INFLUENCED_BY]->(sample)
OPTIONAL MATCH (creator)-[r:RELEASED|PRODUCED]->(t)
RETURN sample, collect(DISTINCT t) AS tracks, collect(DISTINCT creator) AS creators

4. Producer Sound Architects & Hub Centrality

MATCH (p:Producer)-[:PRODUCED]->(t:Track)
OPTIONAL MATCH (a:Artist)-[:RELEASED]->(t)
WITH p, count(DISTINCT t) AS trackCount, count(DISTINCT a) AS artistCount,
     collect(DISTINCT a.name) AS artists
RETURN p.name AS producer, p.signatureTag AS tag, trackCount, artistCount, artists
ORDER BY artistCount DESC, trackCount DESC

5. Circular Collaboration Rings / Cliques (Hard in SQL)

MATCH (a:Artist)-[:COLLABORATED_WITH]->(b:Artist)
MATCH (b)-[:COLLABORATED_WITH]->(c:Artist)
MATCH (c)-[:COLLABORATED_WITH]->(a)
WHERE a.id < b.id AND b.id < c.id
RETURN a.name AS artist1, b.name AS artist2, c.name AS artist3

---

5. Security Audit & Hardening (Vibe Secure Me)

AfroGraph was defensively hardened and audited via Vibe Secure Me:

1. Unauthenticated DB Mutation Guard (CWE-306 / OWASP A01): Protected POST /api/seed with ADMIN_SEED_SECRET bearer validation.
2. Cypher Injection & Exhaustion Defense (CWE-89 / OWASP A03): Enforced Read-Only execution (blocking CREATE, MERGE, DELETE, SET, DROP) with auto-appended LIMIT 100 in /api/query.
3. Label Whitelist Validation (CWE-89): Sanitized /api/graph inputs against a strict ALLOWED_LABELS enum.
4. Information Disclosure Prevention (CWE-200 / OWASP A05): Masked internal CognoDB instance IDs in public health endpoints.
5. HTTP Security Headers & Image Isolation (CWE-693): Configured X-Frame-Options: DENY, nosniff, and restricted image sources to trusted CDN domains.

---

6. Quick Setup & Run

1. CognoDB Instance

1. Create a free instance on console.cognodb.com.
2. Copy your Bolt URI and generated password.

2. Environment Variables (.env.local)

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

3. Install, Seed & Run

npm install
npm run seed     # Seeds realistic Afrobeats dataset into CognoDB
npm run dev      # Starts Next.js app on http://localhost:3000

---

7. Project Structure

├── scripts/
│   └── seed.ts                  # CLI dataset seeder with index constraints
├── src/
│   ├── app/
│   │   ├── api/
│   │   │   ├── graph/route.ts   # Neighborhood & category filtering API
│   │   │   ├── health/route.ts  # Database connection health & latency API
│   │   │   ├── lineage/route.ts # Talent tree & sample lineage API
│   │   │   ├── path/route.ts    # Shortest path / Degrees of separation API
│   │   │   ├── query/route.ts   # Parameterized Cypher query runner API
│   │   │   ├── seed/route.ts    # Admin database seed endpoint
│   │   │   └── stats/route.ts   # Graph analytics & producer centrality API
│   │   ├── cypher/page.tsx      # Interactive Cypher Studio & SQL benchmark
│   │   ├── labels/page.tsx      # Record label talent trees & blast radius
│   │   ├── paths/page.tsx       # Degrees of separation shortest path finder
│   │   ├── samples/page.tsx     # Musical DNA & sample heritage lineage
│   │   └── page.tsx             # Main interactive ecosystem graph canvas
│   ├── components/graph/
│   │   ├── GraphCanvas.tsx      # High-DPI D3 force-directed canvas with pan/zoom/drag
│   │   └── NodeDetailsModal.tsx # Node inspection slide-over drawer
│   └── lib/
│       ├── neo4j.ts             # CognoDB Bolt driver singleton & session pool
│       ├── cypher.ts            # openCypher query catalog & documentation
│       └── seed-data.ts         # Realistic Afrobeats dataset

---

8. AI Assistance Disclosure

In alignment with the assignment guidelines, AI agent assistance was used during development for troubleshooting tricky canvas rendering/simulation race conditions, benchmarking parameterized queries, and refining documentation structure.

---

9. License

MIT — Built by Ajibola Akelebe for Wexa AI.