Vitral is a framework for reproducible design studies in visual analytics. It structures the design study process as a knowledge pipeline extracting knowledge from heterogeneous study artifacts, representing it as a relational graph, and supporting reasoning across that graph at the level of individual artifacts and across the full study ecosystem.
- Shard canvas: Represent design study artifacts (papers, transcripts, sketches, screenshots, code) as typed, linked knowledge units (shards)
- Sharding: Automatically decompose uploaded files into shard trees using LLMs
- Provenance timeline: Record the full evolution of the knowledge graph across the study lifecycle
- Pattern book: Match requirements to established VA system components from the literature
- Codebase integration: Link GitHub commits and files to design decisions through an OAuth connection
- AI assistant: Query and ask analytical question about shards using natural language
- Export: Generate a structured Markdown report or a portable
.viarchive of the full study
- Docker and Docker Compose v2
- An OpenAI API key
- (Optional) A GitHub OAuth App for codebase integration
git clone https://github.com/urban-toolkit/vitral.git
cd vitralCreate a .env file at the repository root. The minimal required content is:
# Required
OPENAI_API_KEY=sk-...
# GitHub OAuth (required for codebase integration)
GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=
# Auth cookie secret (any random string)
COOKIE_SECRET=change-me-to-a-random-string
# Database (default values work for local Docker)
POSTGRES_USER=vitral
POSTGRES_PASSWORD=vitral
POSTGRES_DB=vitral
DATABASE_URL=postgres://vitral:vitral@postgres:5432/vitral
# MinIO object storage (default values work for local Docker)
MINIO_ROOT_USER=vitralminio
MINIO_ROOT_PASSWORD=vitralminio
S3_ACCESS_KEY_ID=vitralminio
S3_SECRET_ACCESS_KEY=vitralminioDevelopment (hot reload on source changes):
docker compose --file docker-compose.dev.yml up --watchFrontend: http://localhost:5173 · Backend: http://localhost:3000
Production:
docker compose --file docker-compose.yml upFrontend: http://localhost:9898
🕒 Coming soon, stay tuned!
Vitral is a full-stack TypeScript application composed of the following services, all orchestrated via Docker Compose:
| Service | Description |
|---|---|
vitral |
React + Vite frontend |
backend |
Node.js (Fastify) API server |
postgres |
PostgreSQL 18 with pgvector for embedding storage |
minio |
S3-compatible object storage for uploaded files |
docling-serve |
Document parsing service for PDF/Office files |
Gustavo Moreira (UIC)
Luc Renambot (UIC)
Daniel de Oliveira (UFF)
Marcos Lage (UFF)
Fabio Miranda (UIC)
MIT — free for research and commercial use.