Case study · 01 / 03
Project overview
A shared workspace where a group collects sources, writes a report and asks an AI that stays grounded in those sources. Charts, tables, calculations and generated claims keep provenance back to the source file, fragment, dataset or executed analysis.
- Status
- Active development
- Source
- Public repository
Problem
Research material lives in many formats (PDFs, DOCX files, spreadsheets, datasets) while the report is written somewhere else. When an AI assistant answers without pointing back to that material, its claims cannot be checked, and a chart or table cannot be tied to the data that produced it. ResearchHub starts from the opposite premise: every generated claim and every computed result stays traceable to its source.
Product and users
For: students and researchers working in teams. What the workspace lets them do:
- Add PDFs, DOCX files, spreadsheets and datasets as versioned sources
- Ask questions answered only from the selected sources, with traceable citations
- Write a shared report together in realtime, with comments on selected text
- Inspect a dataset and run computations in an isolated sandbox
- Insert computed tables and charts into the report with provenance back to the exact inputs
My contribution
GitHub lists a single contributor for this repository: me. The Spring Boot backend, the React frontend, the Python worker, the infrastructure code and the documentation are my own work.
- Backend
- Spring Boot modular monolith: workspace authorization, durable PostgreSQL-backed job dispatch, a structured model gateway with audited calls.
- Frontend
- React and TypeScript: workspace, source pages, the collaborative report editor with comments, and analysis results.
- AI / data worker
- Internal Python FastAPI worker for source extraction, chunking and embeddings, plus the pinned scientific sandbox image.
- Quality and delivery
- Coverage gates, architecture decision records, Bicep infrastructure with offline validation, a one-command local demo.
Architecture
A Spring Boot modular monolith owns product logic, authorization and a durable job dispatcher backed by PostgreSQL. An internal Python worker extracts, chunks and embeds sources; Spring indexes the chunks in pgvector. Realtime editing runs in a separate Hocuspocus service that uses short-lived credentials issued by Spring.
React · TypeScript · TanStack Query
Tiptap / ProseMirror · Yjs
React · TypeScript
Tiptap · Yjs
Realtime collaboration server
Credentials issued by Spring
Realtime sync
Yjs documents
Java 25 · Spring Boot 4.1
Authorization · job dispatcher · model gateway
Java 25 · Boot 4.1
Auth · dispatcher
Python 3.13 · extraction
Chunking · embeddings
Python 3.13
Ingest · embeddings
Sessions · quotas · job queue
Documents · vector search
+ pgvector
State · vectors
Versioned source files
Azurite for local runs
Azure / Azurite
Source files
Spring owns everything with product meaning: who may see a workspace, which job runs next, what a citation points at. Python owns the AI, data and scientific work and is only ever called by Spring, so the Java domain never depends on that ecosystem.
Key engineering challenges
Keeping claims traceable
Generated text must stay linked to the exact source chunks it relies on, across versioned sources, and a question with no supporting evidence must say so.
Running generated code safely
Analyses execute in a pinned Docker sandbox with limits, durable execution records and reruns that preserve earlier evidence.
Realtime collaborative editing
Shared documents on Yjs, Hocuspocus and Tiptap. Every accepted edit is committed before it is broadcast, and the state is stored atomically in PostgreSQL.
Authorization and workspace boundaries
Access to sources, documents and AI features is scoped by workspace and enforced by the server, including calls between internal services.
Technical decisions and trade-offs
| Decision | Why | Trade-off |
|---|---|---|
| Spring modular monolith, with Python only for AI and data work | Product logic and authorization stay in one place, while extraction, embeddings and scientific computation use the Python ecosystem. | Two runtimes and an internal contract to maintain. |
| Durable processing in PostgreSQL (ADR-011) | Sessions, quotas and job dispatch share one transactional store, with no extra infrastructure. | No Redis or Service Bus. Scaling evidence is limited to recorded local two-instance tests. |
| Immutable source versions (ADR-005) | A citation or an analysis can always be traced to the exact bytes it used. | No complete retention or erasure workflow yet; it is proposed in ADR-014. |
| Docker sandbox for generated analysis code (ADR-008) | Filesystem, network and resource limits around execution, with results that can be reproduced. | Local isolation does not prove isolation on Azure. A cloud runner is only proposed (ADR-015). |
| Azure as Bicep infrastructure code, validated offline (ADR-017) | A reproducible definition of the infrastructure without paying for a standing cloud environment. | No subscription deployment is recorded, so there is no claim of cloud availability. |
Stack
Backend & AI worker
- Java 25
- Spring Boot 4.1
- Maven
- Flyway
- Python 3.13
- FastAPI
Frontend & realtime
- React
- TypeScript
- Webpack
- TanStack Query
- Tiptap / ProseMirror
- Yjs
- Hocuspocus
Data & infrastructure
- PostgreSQL 17
- pgvector
- Azure Blob Storage / Azurite
- Docker
- Bicep (Azure IaC)
Testing and quality
Integration tests run against real PostgreSQL 17 and Azurite containers (Testcontainers), and line-coverage gates are enforced per module. The repository itself states that it is not production-ready.
- Coverage gates
- At least 80% line coverage, enforced separately for the source-processing, AI / retrieval and analysis modules (Maven) and for the Python worker (pytest).
- Kinds of tests
- Java integration tests with Testcontainers, pytest for the worker, Jest for the frontend, browser end-to-end checks, and opt-in sandbox attack and cleanup tests.
- Evidence limits
- Local runs only. No hosted release, no live Azure validation and no production claim.
Screenshots
Pinned screenshots from a local run of the project. It is not deployed, so there is no live demo.
Source code
Public repositoryCase studyThis page
igorkadziela.dev/projects/researchhub