Alexandria is a document management and knowledge extraction platform. Users upload documents, e.g., research papers, reports, manuals, meeting notes, and the system automatically organizes, tags, and summarizes them. Users get a concise summary and can ask questions about their documents, instead of having to read through a 40-page report to find what they need.
The core workflow is: Upload a document, get an auto-generated summary with extracted key entities, browse and search your knowledge base, and optionally query the GenAI for specific answers concerning your uploaded content.
Alexandria consists of three main subsystems orchestrated via Docker Compose and Traefik:
- Client: A React SPA serving as the web interface.
- Server: Three Spring Boot microservices (user-service, knowledgebase-service, qa-service) exposing REST APIs, backed by PostgreSQL with a schema per service.
- GenAI: A Python/FastAPI service using LangChain to extract entities and summarize uploaded documents.
Each subsystem lists its responsible team member in the System Overview.
Our docker-compose.yml includes both pre-built image references and local build contexts. You can choose to pull images for instant startup or build them locally.
Pull and Run (Fastest):
docker compose pull && docker compose up -d- Open http://localhost/ to view the site.
- A test user is provided for quick access to the main page: username
testuser, passwordtestpassword.
Build and Run (For Development):
To build the images from your local source: docker compose up --build --force-recreate
The stack boots with working defaults, but the GenAI features (document summaries, tag and entity extraction, semantic search, and Q&A) call an external LLM and need an API key. Without one the app still runs and everything else works; only the AI calls return an error. Set LLM_API_KEY in a .env file before using those features. See GenAI configuration for the provider options and .env.example for the variable.
For local development, docker compose up works out of the box; safe defaults are embedded in docker-compose.yml. The one exception is LLM_API_KEY (see above): it has no usable default, so the GenAI features stay disabled until you set it. For production or CI, copy .env.example to .env and set the values as needed.
- Make sure to remove all containers and docker volumes if you change to a local .env file. Otherwise, e.g., the postgres service will use the old password, leading to failed connections on the server side. This can be achieved by running
docker compose rm <container>anddocker volume rm <volume>.
The REST API is documented from api/openapi.yaml, our single source of truth. A Redoc render is published to GitHub Pages whenever the spec changes on main:
https://aet-devops26.github.io/team-bnd/
The per-service Swagger UIs are also available locally through Traefik (see the routes below).
All services are accessed through Traefik as the reverse proxy. See docs/Traefik.md for architecture, routing, and configuration details.
Quick reference:
| URL | Service |
|---|---|
| http://localhost/ | Client |
| http://localhost/api/v1/... | Spring API |
| http://localhost/user-service/docs | user-service API docs |
| http://localhost/knowledgebase-service/docs | knowledgebase-service API docs |
| http://localhost/qa-service/docs | qa-service API docs |
| http://localhost/genai/docs | GenAI API documentation |
| http://localhost/auth/ | Keycloak |
| http://localhost/grafana/ | Grafana dashboards |
| http://localhost/prometheus/ | Prometheus |
- Azure VM (Terraform + Ansible): Provisioning details live under
infra/azure/README.md. - Kubernetes (Helm): Cluster deployment and troubleshooting details live under
infra/k8s/README.md.
GitHub Actions runs both CI and CD. The workflows live in .github/workflows/.
On every pull request, ci.yml runs the jobs whose paths changed: it builds each service (Spring, client, GenAI), runs their tests with coverage, lints everything (Spotless, SpotBugs, ESLint, Hadolint, yamllint), checks the committed OpenAPI spec is still in sync, builds the Docker images and scans them with Trivy, then brings the whole stack up with docker compose for a smoke test and the Playwright E2E suite. codeql.yml adds the CodeQL security scan. A failing pipeline blocks the merge.
On a push to main, the same ci.yml pushes the images to GHCR tagged with the short commit SHA (and latest), then deploys: the deploy-stud job runs helm upgrade against the Rancher/Kubernetes and the deploy job runs the Ansible deploy role for the Azure VM. deploy-api-docs.yml publishes the Redoc API docs to GitHub Pages when the spec changes.
Per-environment specifics are in infra/k8s/README.md and infra/azure/README.md.
This repository uses pre-commit hooks to enforce code quality, formatting, and OpenAPI spec validity. Install pre-commit and run pre-commit install after cloning.
On every git commit, these checks run automatically. For a full list of enforced hooks and their configurations, refer to .pre-commit-config.yaml.
To run the full hook set manually:
pre-commit run --all-files
Three Spring Boot microservices (user-service, knowledgebase-service, qa-service) that split the former monolith along its package boundaries, sharing one Postgres instance with a schema per service.
For local server development, see services/spring/README.md.
React SPA serving as the web client.
For local client development, see services/client/README.md.
Python/FastAPI service using LangChain to extract entities and summarize documents.
For local Python dev, see services/genai/README.md.
Prometheus scrapes metrics from each Spring service (/actuator/prometheus, one job per service), GenAI (/genai/metrics), Traefik, and the SeaweedFS object storage (s3-storage:9091/metrics), and Grafana visualizes them. Both run as part of docker compose up.
- Grafana: http://localhost/grafana/ (built-in admin login
admin/admin, override withGRAFANA_ADMIN_PASSWORD; or "Sign in with Keycloak" using a realm user) - Prometheus: http://localhost/prometheus/
Grafana login goes through Keycloak via OpenID Connect (generic OAuth against the grafana client in the alexandria realm). Realm users with the grafana-admin role land as Grafana Admins, everyone else as Viewers. The built-in admin login stays available as a fallback.
Dashboards are provisioned automatically under the "Alexandria" folder: an overview (request rate, errors, latency across services), an aggregate Spring dashboard plus one per Spring service (JVM, GC, threads, DB pool), a GenAI dashboard (request rate, latency, process memory), and an object storage dashboard (S3 request rate and latency, in-flight requests, disk usage). Dashboard JSON and the Prometheus scrape and alert config live under infra/prometheus and infra/grafana.
The GenAI service can emit OpenTelemetry traces so you can see where a request spends its time, the query embedding vs. the LLM call. It's off by default; bring it up with the tracing overlay, which adds a local Jaeger and points GenAI at it:
docker compose -f docker-compose.yml -f docker-compose.tracing.yml upJaeger UI is then at http://localhost/jaeger/ (service alexandria-genai). Details are in services/genai/README.md.