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

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. Setup (first time only)
./scripts/quick-start.sh

# 2. Start backend (Terminal 1)
nix develop
cd backend
uvicorn app.main:app --reload

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

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

Access:

• Frontend: http://localhost:5173
• Backend API Docs: http://localhost:8000/docs
• Backend Health: http://localhost:8000/health

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]