AgenticCode

AI-agent-optimized code analysis platform — parse, store, enrich, and query source code as a graph.

AgenticCode ingests source code (Natural/Software AG and Java), parses it into a unified AST, persists it in Neo4j, enriches it with semantic information (call graphs, DB accesses, data structures), and exposes everything through an agent-ready REST + MCP API.

---

Architecture

flowchart TD
    subgraph Sources["Source Files"]
        N([Natural\nSoftware AG])
        J([Java])
        PY([Python\n_planned_])
        CB([COBOL\n_planned_])
    end

    subgraph Parsers["Parser Layer"]
        NP["NaturalParser\n<i>custom implementation</i>"]
        JP["JavaParser\n<i>com.github.javaparser</i>"]
        PI["LanguageParser SPI\n<i>shared interface + unified AST schema</i>"]
    end

    subgraph Store["AST Store"]
        NEO[("Neo4j 5.x\nGraph Database\nModules · Functions · Variables\nData Structures · DB Tables")]
    end

    subgraph Enrichment["Enrichment Layer"]
        CG["CallGraphEnricher\nPERFORM / CALLNAT → CALLS edges"]
        DB["DbAccessEnricher\nREAD / FIND / STORE → READS / WRITES edges"]
        ID["IdentifierIndexEnricher\ncross-module variable index"]
        DS["DataStructureEnricher\nDEFINE DATA → USES_TYPE edges"]
    end

    subgraph API["Agentic API — Quarkus"]
        REST["REST API\nJAX-RS · RESTEasy Reactive"]
        MCP["MCP Endpoint\ntool-use optimized"]
    end

    subgraph Agents["AI Agents"]
        AG(["Claude / LLM Agent\ncall graph · DB access · identifier search\ncode generation · program analysis"])
    end

    N --> NP
    J --> JP
    PY --> PI
    CB --> PI
    NP --> PI
    JP --> PI
    PI --> NEO
    NEO --> CG & DB & ID & DS
    CG & DB & ID & DS --> REST
    CG & DB & ID & DS --> MCP
    REST --> AG
    MCP --> AG

---

Key API Tools (Agent-Facing)

Endpoint	Description
POST /api/ingest	Parse and ingest source files into the graph
GET /api/modules/{name}/callers	Who calls this module?
GET /api/modules/{name}/callees	What does this module call?
GET /api/modules/{name}/db-accesses	DB tables accessed and mode (READ/WRITE)
GET /api/search/identifier?name=	Find an identifier across all modules
MCP tools/*	All of the above as MCP tool-use endpoints

---

Tech Stack

Component	Technology
Server	Quarkus (latest stable)
Language	Java 21 — Records, Sealed Classes, Virtual Threads
Graph DB	Neo4j 5.x via neo4j-java-driver
REST	RESTEasy Reactive (JAX-RS)
Natural Parser	Custom implementation
Java Parser	JavaParser
Tests	JUnit 5 + RestAssured + Testcontainers
Build	Maven (multi-module)

---

Neo4j Graph Schema

erDiagram
    MODULE ||--o{ FUNCTION : CONTAINS
    FUNCTION ||--o{ FUNCTION : CALLS
    FUNCTION ||--o{ VARIABLE : READS
    FUNCTION ||--o{ VARIABLE : WRITES
    FUNCTION ||--o{ DB_TABLE : READS
    FUNCTION ||--o{ DB_TABLE : WRITES
    FUNCTION ||--o{ DATA_STRUCTURE : USES_TYPE
    MODULE {
        string id
        string name
        string language
        string sourceFile
    }
    FUNCTION {
        string id
        string name
        int startLine
        int endLine
    }
    VARIABLE {
        string id
        string name
        string dataType
    }
    DATA_STRUCTURE {
        string id
        string name
        string scope
    }
    DB_TABLE {
        string id
        string name
        string dbType
    }

---

Project Structure

agenticcode/
├── api-server/          # Quarkus application (REST + MCP)
├── parser-core/         # Shared AST model + LanguageParser SPI
├── parser-natural/      # Custom Natural/Software AG parser
├── parser-java/         # Java parser (JavaParser-based)
├── neo4j-store/         # Neo4j persistence + Cypher queries
└── docs/
    ├── ast-schema.md
    ├── natural-grammar.md
    ├── api-endpoints.md
    └── enrichment-pipelines.md

---

Getting Started

Prerequisites: Java 21+, Maven 3.9+, Docker

# Clone and build
git clone https://github.com/your-org/agenticcode.git
cd agenticcode
mvn clean install

# Start Neo4j
docker run -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/agenticcode \
  neo4j:5

# Run in dev mode (hot reload)
cd api-server && mvn quarkus:dev

The API is available at http://localhost:8080/api and the Neo4j browser at http://localhost:7474.

---

Supported Languages

Language	Status	Parser
Natural (Software AG)	🚧 In development	Custom
Java	🚧 In development	JavaParser
Python	📋 Planned	—
COBOL	📋 Planned	—

---