Enterprise Graph Platform

Monorepo scaffold cho MVP phân tích mạng lưới doanh nghiệp, nguồn tin thị trường, đối thủ và tín hiệu truyền thông.

MVP scope

• Dashboard cho số liệu tổng quan, watchlist và sector nóng.
• Graph Explorer để mở rộng 1-2 hop quan hệ doanh nghiệp trong Neo4j.
• Data Source Manager để quản lý RSS, website, API và hàng đợi ingest.
• Sentiment Report và Entity Detail page làm khung cho lớp insight kế tiếp.
• Pipeline nền gồm Spring Boot services, Kafka, Neo4j, PostgreSQL và Crawl4AI worker.

Cấu trúc repo

backend/
  gateway-service/
  ingestion-service/
  graph-query-service/
  report-service/
  shared-kernel/
frontend/
infra/
crawler-worker/
seed/
scripts/
evaluation/
achitecture.md

Kiến trúc hiện tại

• gateway-service: entry point cho frontend, gom route tới các service nội bộ.
• ingestion-service: quản lý nguồn crawl, job ingest và phát event document.ingested vào Kafka.
• graph-query-service: truy vấn graph doanh nghiệp từ Neo4j, đồng thời consume document.crawled để dựng node-edge rule-based.
• report-service: dashboard/sentiment API ban đầu cho MVP.
• crawler-worker: worker Python dùng Crawl4AI để crawl website/API rồi callback về Java ingestion-service.

Công nghệ đã chốt

• Backend: Java 21, Spring Boot 3.4, Spring Cloud Gateway, Spring Data JPA, Spring Data Neo4j, Kafka.
• Frontend: React, TypeScript, Vite, Cytoscape.js, Recharts.
• Data layer: PostgreSQL cho metadata và raw crawl, Neo4j cho graph quan hệ.
• Messaging: Kafka + Kafka UI.
• Crawl: Crawl4AI worker tách riêng để không ép Java backend gánh tác vụ crawl nặng.

Chạy local

1. Hạ tầng

cp .env.example .env
docker compose -f infra/docker-compose.yml up -d

Lưu ý: local dev stack dùng Redpanda tương thích Kafka API. Host machine dùng localhost:29092, còn service trong Docker dùng kafka:9092.

2. Backend

Repo đã có Gradle wrapper trong backend/gradlew. Máy local vẫn cần Java 21 để chạy trực tiếp ngoài Docker.

cd backend
./gradlew :gateway-service:bootRun
./gradlew :ingestion-service:bootRun
./gradlew :graph-query-service:bootRun
./gradlew :report-service:bootRun

2b. Chạy backend bằng Docker

docker compose -f infra/docker-compose.yml -f infra/docker-compose.app.yml up --build

3. Frontend

cd frontend
npm install
npm run dev

4. Crawler worker

cd crawler-worker
python -m venv .venv
source .venv/bin/activate
pip install -e .
uvicorn app.main:app --reload --port 8090

Hoặc chạy crawler cùng stack:

docker compose -f infra/docker-compose.yml -f infra/docker-compose.app.yml up --build crawler-worker

API mẫu

• Gateway: http://localhost:8080
• Ingestion create source: POST /ingestion/api/v1/sources
• Ingestion enqueue document: POST /ingestion/api/v1/documents/ingest
• Ingestion store crawled document: POST /ingestion/api/v1/documents/crawled
• Graph explorer: GET /graph/api/v1/graph/company/{slug}
• Dashboard report: GET /reports/api/v1/reports/dashboard

Seed data cho đồ án

• Source seed ở seed/crawl-sources.json
• URL demo ở seed/demo-article-urls.json
• Script nạp source qua API ở seed/seed-sources.sh

Ví dụ:

chmod +x seed/seed-sources.sh
./seed/seed-sources.sh

Crawl batch dữ liệu demo thật:

chmod +x scripts/run_demo_crawl.py
python3 scripts/run_demo_crawl.py

Đánh giá thực nghiệm

• Script lấy metrics đồ án ở scripts/evaluate_thesis_metrics.py
• Template chấm tay precision ở evaluation/manual-relation-review.csv
• Hướng dẫn đánh giá ở docs/evaluation-guide.md
• Roadmap scale và lựa chọn GraphRAG/LightRAG/GraphCAG ở docs/scaling-roadmap.md

python3 scripts/evaluate_thesis_metrics.py

Trạng thái hiện tại

1. Backend Java đã có wrapper, Docker build path, gateway routing bằng env và pipeline Kafka cơ bản.
2. Frontend đã gọi API thật qua gateway.
3. Crawl worker đã có thể callback về Java ingestion-service và có script crawl batch demo.
4. Rule-based graph projection đã được harden bằng alias catalog mở rộng và chống duplicate document.