webref

A Python project for web reference management, built with quality and maintainability as core values.

Project Constitution

This project follows a formal constitution that establishes binding principles for all development work. The constitution ensures consistent quality, testing discipline, user experience, and performance across the codebase.

Constitutional Principles:

1. Code Quality & Maintainability - Clear, consistent, maintainable code with proper typing and documentation
2. Testing Discipline - ≥80% coverage, automated testing for all functionality
3. User Experience Consistency - Intuitive, accessible, consistent interfaces
4. Performance & Efficiency - Performance-first design with bounded resources

📖 Full constitution: .specify/memory/constitution.md

Documentation

• 📚 Getting Started Guide - Complete setup walkthrough
• 🔧 Nix Services - Service management
• 📋 Specification - Requirements & design
• 📊 Milestones - Phase completion reports

Development Environment

This project uses Nix flakes for reproducible development environments:

# Enter development shell (from flake.nix)
nix develop

# Or use direnv for automatic activation
direnv allow  # .envrc already configured

Included tools:

• Python 3.13 with all backend dependencies (FastAPI, SQLAlchemy, pytest, psycopg2, etc.)
• Node.js + npm for frontend development
• PostgreSQL client tools
• MinIO client
• Ruff (Python linter/formatter)
• All project dependencies from flake.nix

Quick Start

# 1. Enter Nix development environment
nix develop

# 2. Start development services (PostgreSQL + MinIO)
./scripts/dev-services.sh start

# 3. Setup backend (first time only)
cd backend
alembic upgrade head
cd ..

# 4. Start backend (Terminal 1)
cd backend
uvicorn app.main:app --reload

# 5. Start frontend (Terminal 2)
cd frontend
npm install  # first time only
npm run dev

# 6. Test authentication (Terminal 3)
./scripts/test-auth.sh

Access:

• Frontend: http://localhost:5173
• Backend API Docs: http://localhost:8000/docs
• MinIO Console: http://localhost:9001
• PostgreSQL: psql -h localhost -U webref webref

Code Quality & Linting

Unified Linting (All Languages)

# Check all code (Python + TypeScript/Svelte)
./scripts/lint.sh
# OR using nix:
nix run .#lint

# Auto-fix all issues
nix run .#lint-fix

Git Hooks (Automatic)

Install git hooks to run linting automatically:

./scripts/install-hooks.sh

This installs:

• pre-commit: Runs linting before each commit
• pre-push: Runs tests before push (optional)

To skip hooks when committing:

git commit --no-verify

Manual Linting

Backend (Python):

cd backend
ruff check app/          # Check for issues
ruff check --fix app/    # Auto-fix issues  
ruff format app/         # Format code

Frontend (TypeScript/Svelte):

cd frontend
npm run lint             # ESLint check
npm run check            # TypeScript check
npx prettier --check src/  # Prettier check
npx prettier --write src/  # Auto-format

Project Structure

webref/
├── .specify/                   # Project governance and templates
│   ├── memory/
│   │   └── constitution.md     # Project constitution
│   └── templates/
│       ├── plan-template.md    # Planning document template
│       ├── spec-template.md    # Specification template
│       ├── tasks-template.md   # Task tracking template
│       └── commands/
│           └── constitution.md # Constitution amendment workflow
├── backend/                    # FastAPI backend application
│   ├── app/                    # Application code
│   ├── tests/                  # pytest test suite
│   └── pyproject.toml          # Python dependencies
├── frontend/                   # Svelte + Konva.js frontend
│   ├── src/                    # Application code
│   ├── tests/                  # Vitest test suite
│   └── package.json            # Node dependencies
├── nixos/                      # NixOS configuration and tests
│   ├── tests.nix               # NixOS VM integration tests
│   └── gitea-runner.nix        # Gitea Actions runner config
├── flake.nix                   # Nix flake (dependencies & dev shell)
├── .envrc                      # direnv configuration
└── README.md                   # This file

Using the Specification System

Planning a Feature

1. Copy .specify/templates/plan-template.md to .specify/plans/[feature-name].md
2. Fill in objectives, scope, and technical approach
3. Complete the Constitution Alignment Check to verify adherence to principles
4. Review with team before proceeding to specification

Writing a Specification

1. Copy .specify/templates/spec-template.md to .specify/specs/[feature-name].md
2. Define functional and non-functional requirements
3. Each requirement must address constitutional alignment (testing, UX, performance)
4. Include clear acceptance criteria for validation

Managing Tasks

1. Copy .specify/templates/tasks-template.md to .specify/tasks/[sprint-name].md
2. Organize tasks by constitutional principle category:
   • 🏗️ Implementation (Code Quality)
   • 🧪 Testing (Testing Discipline)
   • 👤 User Experience (UX Consistency)
   • ⚡ Performance (Performance & Efficiency)
3. Complete the checklist before closing any task

Amending the Constitution

1. Create a pull request to .specify/memory/constitution.md
2. Include rationale and impact analysis
3. Update version number (MAJOR.MINOR.PATCH)
4. Update all dependent templates
5. Prepend Sync Impact Report

Code Quality Standards

All code must meet these requirements before merge:

• ✅ Linter passing (no errors/warnings)
• ✅ Type hints on all public APIs
• ✅ Tests passing with ≥80% coverage
• ✅ Code review approved
• ✅ Constitution principles verified

Testing

Unit Tests

# Backend tests
cd backend && pytest --cov=app --cov-report=html

# Frontend tests
cd frontend && npm test

# Coverage must be ≥80% per Constitutional Principle 2

NixOS VM Integration Tests

# Run all integration tests in isolated VMs
nix flake check

# Run specific test
nix build .#checks.x86_64-linux.backend-integration
nix build .#checks.x86_64-linux.full-stack
nix build .#checks.x86_64-linux.performance
nix build .#checks.x86_64-linux.security

# Interactive debugging
nix build .#checks.x86_64-linux.backend-integration.driverInteractive
./result/bin/nixos-test-driver

See Tech Research for CI/testing architecture details.

Contributing

1. Read the constitution
2. Follow the planning → specification → implementation flow
3. Ensure all code meets constitutional principles
4. Write tests first (TDD encouraged)
5. Request code review

License

[License information to be added]

Contact

[Contact information to be added]