updates after code review

Author: Yukigeshiki

.github/workflows/api-build.yml

@@ -5,6 +5,10 @@ on:
     branches: [main]
     paths:
       - 'services/query-engine/**'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'services/query-engine/**'
 
 jobs:
   build:

.github/workflows/api-tests.yml

@@ -5,6 +5,10 @@ on:
     branches: [main]
     paths:
       - 'services/query-engine/**'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'services/query-engine/**'
 
 jobs:
   test:
@@ -25,6 +29,14 @@ jobs:
         working-directory: services/query-engine
         run: poetry install --no-root --no-interaction
 
+      - name: Lint
+        working-directory: services/query-engine
+        run: poetry run ruff check .
+
+      - name: Type check
+        working-directory: services/query-engine
+        run: poetry run mypy app tests
+
       - name: Run tests
         working-directory: services/query-engine
         run: poetry run pytest tests/ -v

.github/workflows/ui-build.yml

@@ -5,6 +5,10 @@ on:
     branches: [main]
     paths:
       - 'ui/**'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'ui/**'
 
 jobs:
   build:
@@ -13,5 +17,25 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Enable corepack
+        run: corepack enable
+
+      - name: Install dependencies
+        working-directory: ui
+        run: pnpm install --frozen-lockfile
+
+      - name: Lint
+        working-directory: ui
+        run: pnpm lint
+
+      - name: Build
+        working-directory: ui
+        run: pnpm build
+
       - name: Docker build
         run: docker build -t query-engine-ui:${{ github.sha }} ui

AGENT.md

@@ -2,10 +2,11 @@
 
 ## Project Overview
 
-FastAPI backend service that exposes a LlamaIndex Knowledge Graph query engine over HTTPS. Called by a Kotlin LangGraph4j agent as a tool. Neo4j is the graph store.
+Hybrid RAG system with a FastAPI backend and Vue 3 frontend. The backend exposes a LlamaIndex Knowledge Graph query engine over HTTPS, called by a Kotlin LangGraph4j agent as a tool. Neo4j is the graph store, pgvector handles vector embeddings, and Celery processes ingestion and deletion asynchronously. The UI provides document upload with interactive knowledge graph visualization, a query interface with retrieval mode selection, and document management.
 
 ## Tech Stack
 
+### Backend
 - **Framework**: FastAPI + Uvicorn
 - **Validation**: Pydantic + Pydantic-Settings
 - **Logging**: Structlog (JSON in prod, console in debug)
@@ -18,21 +19,44 @@ FastAPI backend service that exposes a LlamaIndex Knowledge Graph query engine o
 - **Type Checking**: mypy (strict mode)
 - **Testing**: pytest + pytest-asyncio + httpx
 
+### Frontend
+- **Framework**: Vue 3 + TypeScript (Composition API, `<script setup>`)
+- **Build**: Vite + pnpm
+- **Styling**: Tailwind CSS + shadcn-vue
+- **State**: Pinia
+- **Routing**: Vue Router 4
+- **Graph Visualization**: Cytoscape.js
+- **Linting**: ESLint (flat config) with eslint-plugin-vue + typescript-eslint
+
 ## Project Structure
 
 ```
-app/
-├── api/v1/          # API route handlers
-├── connectors/      # Document source connectors (GCS)
-├── core/            # Config (Pydantic Settings), logging, errors, middleware
-├── models/          # Pydantic request/response schemas (CamelModel base)
-├── services/        # Business logic (KnowledgeGraphService, IngestionPipeline)
-└── worker/          # Celery app, background tasks
-tests/               # Pytest test suite
+services/query-engine/       # Backend
+  app/
+  ├── api/v1/                # API route handlers
+  ├── connectors/            # Document source connectors (GCS)
+  ├── core/                  # Config (Pydantic Settings), logging, errors, middleware
+  ├── models/                # Pydantic request/response schemas (CamelModel base)
+  ├── services/              # Business logic (KnowledgeGraphService, IngestionPipeline)
+  └── worker/                # Celery app, background tasks
+  tests/                     # Pytest test suite
+
+ui/                          # Frontend
+  src/
+  ├── components/            # Reusable components (layout, graph, upload, ui)
+  ├── composables/           # Composition API hooks
+  ├── layouts/               # Page layouts
+  ├── router/                # Vue Router config
+  ├── services/              # API client
+  ├── stores/                # Pinia state
+  ├── types/                 # TypeScript interfaces
+  └── views/                 # Page views (QueryView, UploadView)
 ```
 
 ## Commands
 
+### Backend
+
 All commands run from `services/query-engine/`.
 
 ```bash
@@ -58,8 +82,27 @@ poetry run mypy .
 poetry run celery -A app.worker.celery_app:celery_app worker --loglevel=info
 ```
 
+### Frontend
+
+All commands run from `ui/`.
+
+```bash
+# Install dependencies
+pnpm install
+
+# Run dev server
+pnpm dev
+
+# Type check + production build
+pnpm build
+
+# Lint
+pnpm lint
+```
+
 ## Code Conventions
 
+### Backend
 - **Line length**: 100 characters
 - **Type hints**: Required on all functions (strict mypy)
 - **Modern Python syntax**: Use `list[str]` not `List[str]`, etc.
@@ -70,9 +113,15 @@ poetry run celery -A app.worker.celery_app:celery_app worker --loglevel=info
 - **Logging**: Use structlog, not `print()` or stdlib `logging` directly
 - **Docstrings**: PEP 257 — all public modules, classes, functions, and methods must have docstrings. Use triple double quotes. One-line for simple cases, multi-line with summary + blank line + description for complex ones.
 
+### Frontend
+- **Components in `src/components/ui/`** are auto-generated by shadcn-vue and excluded from linting — do not edit directly
+- **Composition API only** — use `<script setup lang="ts">`, no Options API
+- **Import paths**: Use `@/` alias (maps to `src/`)
+
 ## Testing
 
 - Tests live in `tests/` mirroring the app structure
 - Use `pytest-asyncio` with mode `auto`
 - Use `httpx.AsyncClient` with `ASGITransport` for endpoint tests
 - Fixtures defined in `tests/conftest.py`
+- `conftest.py` sets `CELERY_BROKER_URL=""` at import time to force in-memory rate limiter storage — no Redis or Docker required to run tests

services/query-engine/.env.example

@@ -5,7 +5,8 @@ LOG_LEVEL=info
 HOST=0.0.0.0
 PORT=8000
 WORKERS=1
-CORS_ORIGINS=["*"]
+CORS_ORIGINS=[]
+CORS_ORIGIN_REGEX=^https?://(localhost|127\.0\.0\.1)(:\d+)?$
 
 # OpenAI / LlamaIndex
 OPENAI_API_KEY=

services/query-engine/app/api/v1/knowledge_graph.py

@@ -165,7 +165,9 @@ async def get_subgraph(
 @limiter.limit(settings.rate_limit_default)
 async def get_document_graph(
     request: Request,
-    doc_ids: list[str] = Query(..., max_length=50, description="Document IDs (supports multi-chunk docs, max 50)"),
+    doc_ids: list[str] = Query(
+        ..., max_length=50, description="Document IDs (max 50)",
+    ),
     service: KnowledgeGraphService = Depends(get_kg_service),
 ) -> SubgraphResponse:
     """Retrieve the graph for a specific ingested document."""

services/query-engine/app/api/v1/tasks.py

@@ -35,15 +35,16 @@
 @limiter.limit(settings.rate_limit_default)
 async def get_task_status(request: Request, task_id: str) -> TaskStatusResponse:
     """Poll the status of a background task."""
-    result = AsyncResult(task_id, app=celery_app)
+    result: AsyncResult[dict[str, Any]] = AsyncResult(task_id, app=celery_app)
 
     status = _STATUS_MAP.get(result.status, TaskStatus.PENDING)
 
-    task_result = None
+    task_result: SourceIngestResult | DeleteDocumentResult | None = None
     error = None
 
     if result.successful():
-        raw: dict[str, Any] = result.result
+        raw = result.result
+        assert isinstance(raw, dict)
         task_type = raw.get("task_type")
         if task_type == "delete_document":
             task_result = DeleteDocumentResult(**raw)

services/query-engine/app/core/config.py

@@ -20,7 +20,8 @@ class Settings(BaseSettings):
     port: int = 8000
     workers: int = 1
 
-    cors_origins: list[str] = ["*"]
+    cors_origins: list[str] = []
+    cors_origin_regex: str = r"^https?://(localhost|127\.0\.0\.1)(:\d+)?$"
 
     # OpenAI
     openai_api_key: str = ""

services/query-engine/app/main.py

@@ -16,8 +16,8 @@
 from app.core.error_handlers import register_error_handlers
 from app.core.gcs import get_gcs_client
 from app.core.logging import setup_logging
-from app.core.postgres import get_pg_engine
 from app.core.middleware import RequestContextMiddleware
+from app.core.postgres import get_pg_engine
 from app.core.rate_limit import limiter, rate_limit_exceeded_handler
 from app.services.knowledge_graph import KnowledgeGraphService
 from app.services.query_cache import create_query_cache
@@ -45,7 +45,9 @@ async def lifespan(_app: FastAPI) -> AsyncIterator[None]:
     """Handle application startup and shutdown events."""
     setup_logging()
     logger.info("starting", app_name=settings.app_name, version=settings.app_version)
-    pg_engine = get_pg_engine(settings.postgres_uri) if settings.postgres_enabled and settings.postgres_uri else None
+    pg_engine = None
+    if settings.postgres_enabled and settings.postgres_uri:
+        pg_engine = get_pg_engine(settings.postgres_uri)
     cache = create_query_cache(settings, engine=pg_engine)
     _app.state.kg_service = KnowledgeGraphService(
         settings, cache=cache, engine=pg_engine
@@ -80,6 +82,7 @@ def create_app() -> FastAPI:
     app.add_middleware(
         CORSMiddleware,
         allow_origins=settings.cors_origins,
+        allow_origin_regex=settings.cors_origin_regex or None,
         allow_credentials=True,
         allow_methods=["*"],
         allow_headers=["*"],

services/query-engine/app/models/tasks.py

@@ -1,7 +1,6 @@
 """Task status models for background processing."""
 
 from enum import StrEnum
-from typing import Any
 
 from pydantic import Field