Clean up project structure and improve organization

- Move notes/ to reference-material/fasthtml-notes/ (gitignored)
- Move test_files/ to tests/fixtures/ (proper test location)
- Add .gitkeep files for runtime directories (data/, uploads/, exports/)
- Update .gitignore to exclude reference materials and runtime files
- Update Makefile to use 'uv pip' instead of 'pip'
- Expand README project structure to document ALL directories
- Add comprehensive CONTRIBUTING.md guide
- Remove empty static/js directory (no JavaScript used)
- Document which directories are auto-created vs included

This makes the project structure clearer for contributors and ensures
clean clones with proper directory structure.

Author: michael-borck

.gitignore

@@ -88,8 +88,17 @@ src-tauri/gen/
 dist/
 build/
 
-# Reference implementations (read-only)
+# Reference materials (not for distribution)
 reference-implementations/
+reference-material/
 
 # Old requirements files (we use pyproject.toml)
-requirements*.txt
+requirements*.txt
+
+# Runtime directories
+uploads/*
+!uploads/.gitkeep
+exports/*
+!exports/.gitkeep
+data/*
+!data/.gitkeep

CONTRIBUTING.md

@@ -0,0 +1,132 @@
+# Contributing to Curriculum Curator
+
+Thank you for your interest in contributing to Curriculum Curator! This document provides guidelines for contributing to the project.
+
+## Getting Started
+
+1. **Fork the repository** on GitHub
+2. **Clone your fork** locally:
+   ```bash
+   git clone https://github.com/YOUR-USERNAME/curriculum-curator.git
+   cd curriculum-curator
+   ```
+3. **Set up development environment**:
+   ```bash
+   python -m venv .venv
+   source .venv/bin/activate  # Windows: .venv\Scripts\activate
+   uv pip install -e ".[dev]"
+   ```
+4. **Configure environment**:
+   ```bash
+   cp .env.example .env
+   # Edit .env with your settings
+   ```
+
+## Development Workflow
+
+1. **Create a feature branch**:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. **Make your changes** following our coding standards
+
+3. **Run tests and checks**:
+   ```bash
+   make check-all  # Runs lint, type-check, and tests
+   ```
+
+4. **Commit your changes**:
+   ```bash
+   git add .
+   git commit -m "feat: add amazing feature"
+   ```
+
+5. **Push to your fork**:
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+6. **Create a Pull Request** on GitHub
+
+## Coding Standards
+
+### Python Style
+- Follow PEP 8
+- Use type hints where possible
+- Maximum line length: 100 characters
+- Use `ruff` for linting and formatting
+
+### Commit Messages
+Follow conventional commits format:
+- `feat:` New features
+- `fix:` Bug fixes
+- `docs:` Documentation changes
+- `test:` Test additions or changes
+- `refactor:` Code refactoring
+- `chore:` Maintenance tasks
+
+### Testing
+- Write tests for new features
+- Maintain or improve code coverage
+- Tests go in the `tests/` directory
+- Use pytest for testing
+
+## Project Structure
+
+See the [README.md](README.md#project-structure) for detailed project structure.
+
+Key directories:
+- `core/` - Core business logic
+- `plugins/` - Plugin system
+- `views/` - UI components
+- `tests/` - Test suite
+- `docs/` - Documentation
+
+## Development Tools
+
+### Using Make
+```bash
+make dev         # Run development server
+make test        # Run tests
+make lint        # Run linter
+make type-check  # Check types
+make check-all   # Run all checks
+```
+
+### Using Scripts Directly
+```bash
+python scripts/run_dev.py    # Development server
+python scripts/run_tests.py  # Run tests
+python scripts/check_types.py # Type checking
+```
+
+## Areas for Contribution
+
+### Current Priorities
+1. **LLM Integration** - Build content generation pipeline
+2. **Plugin Development** - Create new validators and remediators
+3. **Documentation** - Improve guides and examples
+4. **Testing** - Increase test coverage
+5. **UI/UX** - Enhance user interfaces
+
+### Good First Issues
+Look for issues labeled `good first issue` on GitHub.
+
+## Pull Request Process
+
+1. **Update documentation** if needed
+2. **Add tests** for new functionality
+3. **Ensure all tests pass**
+4. **Update CHANGELOG.md** if applicable
+5. **Request review** from maintainers
+
+## Questions?
+
+- Check existing [issues](https://github.com/michael-borck/curriculum-curator/issues)
+- Read the [documentation](docs/)
+- Ask in discussions or create an issue
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the project's MIT license.

Makefile

@@ -17,10 +17,10 @@ help:
 
 # Install dependencies
 install:
-	pip install -e .
+	uv pip install -e .
 
 install-dev:
-	pip install -e ".[dev]"
+	uv pip install -e ".[dev]"
 
 # Testing
 test:

README.md

@@ -122,34 +122,87 @@ curriculum-curator/
 ├── app.py                  # Main FastHTML application
 ├── init_db.py             # Database initialization script
 ├── pyproject.toml         # Python project configuration
-├── .env.example           # Environment configuration template
+├── .env.example           # Environment configuration template ⭐
+├── Makefile               # Development shortcuts (uses uv)
+│
 ├── core/                  # Core business logic
-│   ├── auth.py           # Authentication system
-│   ├── email_service.py  # Email integration
-│   ├── security.py       # Security utilities
-│   ├── course_manager.py # Course management
+│   ├── auth.py           # Authentication & user management
+│   ├── email_service.py  # Email integration (Brevo)
+│   ├── security.py       # Security utilities & rate limiting
+│   ├── course_manager.py # Course content management
 │   └── teaching_philosophy.py  # Teaching style system
-├── scripts/               # Development & utility scripts
-│   ├── run_dev.py        # Development server with auto-reload
-│   ├── run_tests.py      # Test runner
-│   ├── check_types.py    # Type checking
-│   └── test_plugins.py   # Plugin system testing
-├── plugins/               # Plugin system
-│   ├── base.py           # Base plugin classes
-│   ├── validators/       # Content validators
-│   └── remediators/      # Content improvers
-├── views/                 # UI components
-│   ├── landing.py        # Landing page
+│
+├── components/            # UI components and helpers
+│   ├── layout.py         # Page layout components
+│   ├── upload.py         # File upload handling
+│   ├── analysis.py       # Content analysis display
+│   ├── enhancement.py    # Enhancement suggestions UI
+│   └── comparison.py     # Before/after comparison
+│
+├── views/                 # Page views
+│   ├── landing.py        # Landing/home page
 │   ├── wizard_mode.py    # Step-by-step interface
 │   └── expert_mode.py    # Power user interface
-├── tests/                 # Test suite
-├── docs/                  # Comprehensive documentation
+│
+├── plugins/               # Extensible plugin system
+│   ├── base.py           # Base plugin classes & registry
+│   ├── validators/       # Content validation plugins
+│   │   ├── readability.py
+│   │   ├── structure.py
+│   │   └── similarity.py
+│   └── remediators/      # Content improvement plugins
+│       ├── simplifier.py
+│       └── grammar_fixer.py
+│
+├── scripts/               # Development & utility scripts
+│   ├── run_dev.py        # Dev server with auto-reload
+│   ├── run_tests.py      # Test runner with coverage
+│   ├── check_types.py    # Type checking (basedpyright)
+│   └── test_plugins.py   # Plugin system testing
+│
+├── tests/                 # Comprehensive test suite
+│   ├── conftest.py       # Test configuration
+│   ├── test_auth_system.py
+│   ├── test_plugin_system.py
+│   └── test_teaching_philosophy.py
+│
+├── docs/                  # Documentation
 │   ├── adr/              # Architecture Decision Records
 │   ├── guides/           # User and deployment guides
+│   ├── api/              # API documentation
+│   ├── concepts/         # Conceptual documentation
 │   └── SECURITY.md       # Security overview
-└── data/                  # Local data storage (gitignored)
+│
+├── typings/               # Type stubs for FastHTML
+│   └── fasthtml/         # Custom type definitions
+│
+├── static/                # Static assets (mostly unused)
+│   ├── css/              # Stylesheets (if any)
+│   └── js/               # JavaScript (removed)
+│
+├── data/                  # SQLite database (auto-created)
+├── uploads/               # User uploaded files (auto-created)
+├── exports/               # Generated exports (auto-created)
+│
+└── reference-material/    # Development references (gitignored)
+    ├── fasthtml-notes/   # FastHTML examples & notes
+    └── tauri-version/    # Original implementation
 ```
 
+### Auto-Created Directories
+The following directories are created automatically when needed:
+- `data/` - SQLite database and related files
+- `uploads/` - Temporary storage for uploaded files
+- `exports/` - Generated course materials
+- `__pycache__/` - Python bytecode cache
+- `.ruff_cache/` - Linter cache
+
+### Not Included in Repository
+- `.venv/` - Python virtual environment
+- `reference-material/` - Development notes and references
+- `reference-implementations/` - Previous versions
+- Any `.env` files (use `.env.example` as template)
+
 ## Contributing
 
 We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.