# 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`](.specify/memory/constitution.md)

## Development Environment

This project uses Nix flakes for reproducible development environments:

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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](specs/001-reference-board-viewer/tech-research.md) for CI/testing architecture details.

## Contributing

1. Read the [constitution](.specify/memory/constitution.md)
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]