Engineering Knowledge Assistant (EKA)

AI-powered engineering assistant that understands APIs, codebases, architecture, documentation, and production systems. Ask questions about your stack in natural language — EKA retrieves context from indexed sources and answers via LLM.

Quick Start

# Start infrastructure (PostgreSQL, Redis, Kafka, Neo4j)
docker compose up -d

# Build and run (dev profile — no API keys needed, mock LLM fallbacks)
./gradlew :eka-app:bootRun --args='--spring.profiles.active=dev'

The app starts at http://localhost:8080. Health check: curl http://localhost:8080/actuator/health.

Architecture

Hexagonal (ports-and-adapters) multi-module Spring Boot backend:

eka-backend/
├── eka-common/     # Domain models, DTOs, enums, ports
├── eka-auth/       # OAuth2 (Google, GitHub) + JWT (RS256) + rate limiting
├── eka-embedding/  # Embedding providers (OpenAI, Voyage) + Redis cache
├── eka-ingestion/  # Document ingestion pipeline — connectors (GitHub, GitLab, Confluence, web) → Kafka → processing
├── eka-retrieval/  # Hybrid search — pgvector (vector) + PostgreSQL FTS (keyword) + Cohere reranking
├── eka-chat/       # Chat service, LLM routing, intent detection, prompt templates, SSE streaming
├── eka-graph/      # Knowledge graph (Neo4j) — entity extraction, graph traversal RAG
├── eka-web/        # REST controllers, exception handling, WebSocket
└── eka-app/        # Bootable application assembly

Prerequisites

• Java 21 (not 25 — see build.gradle)
• Docker (for infrastructure — PostgreSQL, Redis, Kafka, Neo4j)
• Gradle wrapper included — no local Gradle install needed

Environment Variables

Variable	Required	Description
OPENAI_API_KEY	For AI features	OpenAI API key (chat + embeddings)
ANTHROPIC_API_KEY	For AI features	Anthropic API key (primary LLM)
COHERE_API_KEY	For reranking	Cohere API key (rerank step)
VOYAGE_API_KEY	Alternative embedding	Voyage AI embedding API key
OLLAMA_BASE_URL	Optional	Local Ollama endpoint (default: http://localhost:11434)
GOOGLE_CLIENT_ID	For OAuth2 login	Google OAuth client ID
GOOGLE_CLIENT_SECRET	For OAuth2 login	Google OAuth client secret
GITHUB_CLIENT_ID	For OAuth2 login	GitHub OAuth client ID
GITHUB_CLIENT_SECRET	For OAuth2 login	GitHub OAuth client secret
JWT_PRIVATE_KEY	Required	RS256 private key (openssl genrsa -out priv.pem 2048)
JWT_PUBLIC_KEY	Required	RS256 public key
TRACING_SAMPLE_RATE	Optional	OpenTelemetry trace sample rate (default: 0.1)

Copy .env.example to .env and fill in the values you need.

Profiles

Profile	Use
dev	Development — debug logging, 100% tracing, no rate limiting, ephemeral JWT keys, mock LLM fallbacks
local	Local run with disabled AI auto-configs, no Kafka consumers

The dev profile generates temporary JWT keys at startup — you don't need to set JWT_PRIVATE_KEY/JWT_PUBLIC_KEY to start exploring.

Commands

# Build everything (compile + test + OWASP check + coverage)
./gradlew build

# Run tests only
./gradlew :eka-test:test

# Integration tests (requires Docker running)
./gradlew :eka-test:integrationTest

# Build fat JAR
./gradlew :eka-app:bootJar

# Run with local profile (no AI, no Kafka consumers)
./gradlew :eka-app:bootRun --args='--spring.profiles.active=local'

Infrastructure Ports

Service	Port
App	8080
Postgres	5432
Redis	6379
Kafka	9092
Neo4j	7687 (Bolt), 7474 (Browser)

Tech Stack

• Language: Java 21 (virtual threads via Project Loom)
• Framework: Spring Boot 3.4.x, Spring WebFlux, Spring AI 1.0.0-M6
• Database: PostgreSQL 16 + pgvector
• Cache: Redis 7
• Messaging: Apache Kafka 7.6
• Search: Vector (pgvector) + full-text (PostgreSQL FTS) + Cohere reranking
• Auth: OAuth2 (Google, GitHub) + JWT (RS256)
• Graph: Neo4j 5 (optional, knowledge graph RAG)
• Observability: Micrometer + OpenTelemetry + Jaeger, Prometheus
• Build: Gradle 9.x, OWASP dependency-check, JaCoCo (≥30% coverage)
• Docs: 12 detailed design docs in docs/

CI/CD

• CI: GitHub Actions — ./gradlew test build dependencyCheckAnalyze on PRs
• CD: Docker build + Helm deploy to Kubernetes on push to main

Documentation

• IMPLEMENTATION.md — design decisions, architecture deep-dive
• docs/ — per-module design docs (auth, DB schema, ingestion, chat, retrieval, testing, deployment)

Contributing

See CONTRIBUTING.md.

License

MIT