159 lines
5.2 KiB
Markdown
159 lines
5.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)
|
|
|
|
## 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.12 with all backend dependencies (FastAPI, SQLAlchemy, pytest, etc.)
|
|
- Node.js + npm for frontend development
|
|
- PostgreSQL client tools
|
|
- MinIO client
|
|
- Ruff (Python linter/formatter)
|
|
- All project dependencies from flake.nix
|
|
|
|
## 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.backend-integration
|
|
nix build .#checks.full-stack
|
|
nix build .#checks.performance
|
|
nix build .#checks.security
|
|
|
|
# Interactive debugging
|
|
nix build .#checks.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]
|
|
|