Developer Overview
Scholarr is a Python 3.12+ FastAPI backend with an async SQLAlchemy ORM layer, PostgreSQL database, and a Vue 3 + TypeScript + Vite frontend.
Stack
| Layer | Technology |
|---|---|
| Backend | Python 3.12+, FastAPI, SQLAlchemy 2.0 (async/asyncpg), Alembic |
| Frontend | TypeScript, Vue 3, Vite, Tailwind CSS |
| Database | PostgreSQL 15 |
| Infrastructure | Multi-stage Docker, Docker Compose |
| Linting | ruff (E, F, W, I, UP, B, SIM, RUF), mypy |
| Testing | pytest, pytest-asyncio |
| Versioning | python-semantic-release, conventional commits |
Quick Start
# Build the dev image and start services
docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build
# Backend: http://localhost:8000 (hot reload enabled)
# Frontend: http://localhost:5173 (Vite dev server with API proxy)
See Local Development for the full setup guide.
Project Layout
app/
├── api/routers/ # FastAPI route handlers
├── auth/ # Session + CSRF middleware
├── db/ # SQLAlchemy models, session factory, migrations
├── services/ # Domain service modules (see Architecture)
│ ├── arxiv/ # arXiv API client, cache, rate limiting
│ ├── crossref/ # Crossref DOI lookups
│ ├── dbops/ # Database integrity + repair operations
│ ├── ingestion/ # Run orchestration, scheduler, safety gates
│ ├── openalex/ # OpenAlex metadata matching
│ ├── portability/ # Import/export workflows
│ ├── publication_identifiers/ # Multi-identifier resolution
│ ├── publications/ # Listing, enrichment, dedup, PDF queue
│ ├── runs/ # Run history, continuation queue
│ ├── scholar/ # HTML parser, source fetch adapters
│ ├── scholars/ # Scholar CRUD, image upload, name search
│ └── unpaywall/ # Unpaywall PDF discovery
├── main.py # App factory, lifespan, middleware stack
frontend/
├── src/
│ ├── components/ # Reusable Vue components
│ ├── theme/presets/ # Color theme presets (light + dark)
│ └── ...
scripts/db/ # Operational database scripts
tests/
├── unit/ # Fast, no-database tests
├── integration/ # Tests requiring database + services
└── fixtures/ # Shared test fixtures