249 lines
7.2 KiB
Markdown
249 lines
7.2 KiB
Markdown
# 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]
|
|
|