A modern HTML-native preprint server for academic research documents. Built with FastAPI, Scroll Press allows researchers to upload and share research manuscripts written in web-native formats (HTML/CSS/JS).

• HTML-native publishing: Upload complete HTML documents with embedded CSS and JavaScript
• Session-based authentication: Secure user registration and login system
• Subject categorization: Organize research by academic disciplines
• Draft and publish workflow: Save drafts and publish when ready
• Scroll cards: Browse recent submissions with rich metadata
• Responsive design: Clean, academic-focused UI with HTMX interactions

• Python 3.11+
• PostgreSQL database
• uv package manager
• just to run common commands

1. Clone the repository

   git clone <repository-url>
   cd press

2. Set up environment

   cp .env.example .env
   # Edit .env with your database URL and port

3. Install dependencies and setup

   just init

4. Start the development server

   just dev

Visit https://localhost:7999 to access Scroll Press (HTTPS with self-signed certificate).

app/
├── auth/               # Session-based authentication
├── models/             # SQLAlchemy database models
├── routes/             # FastAPI route handlers
├── templates/          # Jinja2 templates with component macros
└── database.py         # Async database configuration

static/
├── css/               # Stylesheet
└── images/            # Static assets

tests/                 # Comprehensive test suite

• Backend: FastAPI with async/await patterns
• Database: PostgreSQL with SQLAlchemy 2.0 async
• Authentication: Session-based with in-memory storage
• Frontend: Jinja2 templates with HTMX for dynamic interactions
• Security: HTTPS-only development with self-signed certificates
• Testing: pytest with asyncio support, parallel execution, and Playwright e2e tests

Scroll Press uses different databases for each environment:

Set your DATABASE_URL in .env:

# Local development (adjust username as needed)
DATABASE_URL=postgresql+asyncpg://leo.torres@localhost:5432/press

# Production (Supabase)
DATABASE_URL=postgresql+asyncpg://postgres.xyz:password@aws-0-region.pooler.supabase.com:6543/postgres

# Apply migrations
just migrate
# or: uv run alembic upgrade head

# Create new migration
just migration "description"
# or: uv run alembic revision --autogenerate -m "description"

# Reset database with fresh seed data
just reset-db

• Method: Automated GitHub Actions backups
• Schedule: Daily at 2 AM UTC
• Retention: 30 days (last 7 backups kept)
• Cost: Free using GitHub Actions
• Security: Private artifacts, repository collaborators only

1. Add required secrets to GitHub repository (see BACKUP_SETUP.md)
2. Backups run automatically via .github/workflows/database-backup.yml
3. Manual backups can be triggered from GitHub Actions tab

Plan to upgrade to Supabase Pro Plan ($25/month) for official backups once user base grows:

• 14-day automated backups
• Point-in-time recovery
• Professional support
• Integrated dashboard management

• UUID primary keys
• Email verification and password hashing
• Display names and timestamps

• Academic manuscript storage with HTML content
• Draft/published status workflow
• Version tracking and unique scroll IDs
• Metadata (title, authors, abstract, keywords)

• Academic discipline categorization
• Hierarchical organization for research areas

Scroll Press includes comprehensive testing with both unit/integration tests and end-to-end browser tests.

# Run all tests
just test

# Run with coverage
just test-cov

# Run specific test file
uv run pytest tests/test_main.py -v

E2E tests use Playwright to verify complete user journeys in real browsers.

# Install e2e dependencies (one time)
uv run playwright install chromium firefox

# Start development server
just dev

# Run e2e tests (in another terminal)
just test-e2e

# Or run directly
./scripts/run-e2e-tests.sh

• Registration → Upload → Public Access: Verifies scrolls remain publicly accessible
• Registration → Upload → Account Deletion → Public Access: Verifies scroll persistence after user deletion
• License Selection: Tests CC BY 4.0 and All Rights Reserved license workflows
• Mobile Responsive: Validates mobile upload and interaction flows
• Search & Discovery: Tests content search and subject browsing

See E2E Testing Documentation for detailed information.

1. Run all checks: just check (includes lint, unit tests, and e2e tests)
2. Run tests only: just test
3. Run e2e tests only: just test-e2e
4. Follow existing patterns: Session-based auth, macro components, async/await
5. Write tests: All new features should include test coverage

This project is licensed under the MIT License - see the LICENSE file for details.

For issues and questions, please use the GitHub issue tracker.