Minerva - Knowledge Hub

Minerva is a knowledge hub developed for students, educators, and lifelong learners.

Changelog · Report Bug · Request Feature

---

Table of Contents

• About
• Features
• Tech Stack
• Architecture
• Modules
• Getting Started
• Scripts & Workflows

---

About The Project

Minerva is an AI-powered learning platform where students organize their study materials, then use AI to generate flashcards, summaries, and chat with their content through Retrieval-Augmented Generation (RAG).

---

Features

AI Chat (RAG) Chat with your study material using Retrieval-Augmented Generation, scoped to classes or topics, with real-time streaming and multiple AI personas.	Flashcards, MCQs & Spaced Repetition AI-generated flashcards and multiple choice questions with SM-2 spaced repetition, AI explanations, activity heatmap, and learning statistics.
Smart Search & Content Import Upload PDF, DOCX, Markdown, plain text, images, YouTube videos, and websites. Smart Search provides AI-powered answers within documents with clickable page references.	Study Plans & Exam Prep Create personalized study schedules with exam countdown, progress tracking, daily goals, and readiness projections. Generate AI-powered practice exams with automatic grading.
AI Summaries Auto-generated summaries with configurable style and length. Full LaTeX formula support.	Class Management Organize courses with professor names, course codes, semesters, and exam dates. Track progress across all your classes.
Subscription & Payments Three tiers (Free, Pro, Enterprise) with Stripe checkout, billing portal, and AOP-enforced usage limits.	Platform Google OAuth + password auth, dark/light/system theme, i18n (EN/DE), responsive design, GDPR data export & deletion.

---

Tech Stack

---

Architecture

Browser
  └─► minerva-hub (React SPA, port 3000 dev / 80 prod)
        └─► /api/** proxy ─► minerva-api (Spring Boot, port 8080)
                                ├─► Neo4j (Bolt, port 47686 local)
                                ├─► Redis (port 6379) — cache & queue
                                ├─► AWS S3 / MinIO (port 9002 local) — file storage
                                ├─► AWS Cognito — JWT authentication
                                ├─► OpenAI API — LLM completions
                                ├─► Stripe — payment processing
                                └─► minerva-converter (HTTP + Redis queue, port 8000)
                                        ├─► Redis queue (async document jobs)
                                        └─► AWS S3 — processed documents

Dependency Direction

minerva-hub  →  minerva-api  →  Neo4j / Redis / S3 / OpenAI / Stripe
minerva-api  →  minerva-converter (REST + Redis queue)
minerva-infra  (standalone — provisions cloud resources)

---

Modules

Module	Language / Framework	Description	README
minerva-api	Java 21 + Kotlin, Spring Boot 4.0.1	REST API — business logic, auth, AI, payment	README
minerva-hub	TypeScript, React 18, Vite 7	Single-page web application	README
minerva-converter	Python 3.11, FastAPI	Document processing — conversion, chunking, embeddings	README
minerva-infra	HCL, Terraform	AWS infrastructure (Cognito, S3, Route 53, Secrets Manager, Stripe, Railway)	README
minerva-neo4j	Dockerfile	Neo4j container config for local dev & Railway deployment	README
minerva-redis	Dockerfile	Redis container config for local dev & Railway deployment	README
bash	Bash	CLI tools for infrastructure management (mnv-infra, mnv-setup)	README

---

Getting Started

Full Local Stack (Docker)

The fastest way to get everything running:

./start.sh

This builds all images, starts services via Docker Compose, and opens the browser. Alternatively:

docker compose up --build -d
# Services: neo4j, redis, minio, converter, api, hub
# Hub: http://localhost:80
# API: http://localhost:8080
# Neo4j Browser: http://localhost:47473
# MinIO Console: http://localhost:9003

Individual Services

Frontend only (requires API running):

cd minerva-hub
npm install
npm run dev         # http://localhost:3000 (proxies /api → localhost:8080)

Backend only (requires Neo4j, Redis, MinIO):

docker compose up -d neo4j redis minio
cd minerva-api
SPRING_PROFILES_ACTIVE=local mvn spring-boot:run

Converter only (requires Redis):

docker compose up -d redis
cd minerva-converter
pip install -r requirements.txt
python -m app.worker

Environment Profiles

Profile	Activation	S3	Secrets
local	SPRING_PROFILES_ACTIVE=local	MinIO (localhost:9002)	aws-secretsmanager:minerva/local
test	SPRING_PROFILES_ACTIVE=test	S3 minerva-resources-test	aws-secretsmanager:minerva/test
prod	SPRING_PROFILES_ACTIVE=prod	S3 minerva-resources-prod	aws-secretsmanager:minerva/prod

---

Scripts & Workflows

Build

Target	Command
All Java modules	mvn clean package -DskipTests
API only	mvn clean package -DskipTests -pl minerva-api -am
Frontend	cd minerva-hub && npm run build
Docker (all)	docker compose build

Test & Lint

Target	Command
Java tests + Checkstyle + SpotBugs	mvn verify
Frontend lint	cd minerva-hub && npm run lint
Frontend typecheck	cd minerva-hub && npm run build

Infrastructure

mnv-infra terraform init
mnv-infra terraform plan  --workspace "local"
mnv-infra terraform apply --workspace "local"
# Workspaces: local | test | prod

CI/CD

Workflow	Trigger	Description
pr-validation.yml	Pull request to master	Runs mvn verify + npm run lint && build; required to pass before merge
auto-release.yml	Push to master	Version sync, changelog generation (Claude Code), release PR, GitHub Release
claude-implement-issue.yml	@claude comment on issue	AI-powered issue implementation with auto PR