# 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)

## Documentation

- 📚 **[Getting Started Guide](docs/getting-started.md)** - Complete setup walkthrough
- 🔧 **[Nix Services](docs/development/nix-services.md)** - Service management
- 📋 **[Specification](specs/001-reference-board-viewer/spec.md)** - Requirements & design
- 📊 **[Milestones](docs/milestones/)** - Phase completion reports

## 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. 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)

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

```bash
./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:
```bash
git commit --no-verify
```

### Manual Linting

**Backend (Python):**
```bash
cd backend
ruff check app/          # Check for issues
ruff check --fix app/    # Auto-fix issues  
ruff format app/         # Format code
```

**Frontend (TypeScript/Svelte):**
```bash
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

```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]