Skip to content

Commit b12fb9d

Browse files
michael-borckmichael-borck
committed
Organize project structure and improve documentation visibility
- Move utility scripts to scripts/ folder for cleaner root directory - Keep only app.py and init_db.py in root (standard practice) - Add comprehensive Configuration section to README - Make .env.example more visible with direct link - Update project structure documentation - Add scripts/README.md to document utility scripts - Update Makefile to use pyproject.toml and new script locations This improves project organization while following Python best practices for root directory structure.
1 parent d68c04b commit b12fb9d

File tree

7 files changed

+438
-24
lines changed

7 files changed

+438
-24
lines changed

‎Makefile‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
.PHONY: help install install-dev test test-cov lint type-check format clean run dev
2+
3+
# Default target
4+
help:
5+
@echo "Available commands:"
6+
@echo " make install - Install production dependencies"
7+
@echo " make install-dev - Install all dependencies including dev/test"
8+
@echo " make test - Run tests"
9+
@echo " make test-cov - Run tests with coverage"
10+
@echo " make lint - Run linting (ruff)"
11+
@echo " make type-check - Run type checking (basedpyright)"
12+
@echo " make format - Format code (black)"
13+
@echo " make clean - Clean up generated files"
14+
@echo " make run - Run the application"
15+
@echo " make dev - Run in development mode"
16+
@echo " make check-all - Run all checks (lint, type-check, test)"
17+
18+
# Install dependencies
19+
install:
20+
pip install -e .
21+
22+
install-dev:
23+
pip install -e ".[dev]"
24+
25+
# Testing
26+
test:
27+
python scripts/run_tests.py
28+
29+
test-cov:
30+
pytest --cov=. --cov-report=html --cov-report=term
31+
32+
test-watch:
33+
pytest-watch
34+
35+
# Code quality
36+
lint:
37+
ruff check . --fix
38+
39+
type-check:
40+
python scripts/check_types.py
41+
42+
format:
43+
black .
44+
ruff check . --fix
45+
46+
# Combined checks
47+
check-all: lint type-check test
48+
49+
# Cleaning
50+
clean:
51+
find . -type d -name "__pycache__" -exec rm -rf {} +
52+
find . -type f -name "*.pyc" -delete
53+
find . -type f -name "*.pyo" -delete
54+
find . -type f -name "*.pyd" -delete
55+
find . -type f -name ".coverage" -delete
56+
find . -type d -name "*.egg-info" -exec rm -rf {} +
57+
find . -type d -name ".pytest_cache" -exec rm -rf {} +
58+
find . -type d -name ".ruff_cache" -exec rm -rf {} +
59+
find . -type d -name ".mypy_cache" -exec rm -rf {} +
60+
find . -type d -name "htmlcov" -exec rm -rf {} +
61+
rm -rf build/ dist/
62+
63+
# Running the app
64+
run:
65+
python app.py
66+
67+
dev:
68+
python scripts/run_dev.py
69+
70+
# Database
71+
init-db:
72+
python init_db.py
73+
74+
# Quick development workflow
75+
quick-check: format lint type-check
76+
77+
# Watch for changes and run tests
78+
watch:
79+
watchmedo auto-restart --pattern="*.py" --recursive -- python app.py

‎README.md‎

Lines changed: 140 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,47 +1,163 @@
1-
# Curriculum Curator - Web Edition
1+
# Curriculum Curator
22

3-
A web-based educational content analysis and enhancement tool built with FastHTML and Python.
3+
A pedagogically-aware course content creation platform that helps educators generate high-quality educational materials aligned with their teaching philosophy.
44

55
## Features
66

7-
- **Document Import**: Upload PowerPoint (.pptx) and Word (.docx) files
8-
- **AI-Powered Analysis**: Comprehensive content analysis with learning objectives extraction
9-
- **Enhancement Suggestions**: AI-generated improvements for educational content
10-
- **Content Comparison**: Side-by-side before/after comparison views
11-
- **Export Options**: Export enhanced content to various formats
7+
### 🎓 Teaching Philosophy Integration
8+
- 9 distinct teaching styles (Traditional, Constructivist, Project-Based, etc.)
9+
- Adaptive content generation based on your pedagogical approach
10+
- Teaching style detection questionnaire
11+
12+
### 🧙 Dual User Interfaces
13+
- **Wizard Mode**: Step-by-step guided creation for beginners
14+
- **Expert Mode**: All-in-one power interface for experienced users
15+
16+
### 🔌 Extensible Plugin System
17+
- Built-in validators for content quality, readability, and structure
18+
- Remediators for automatic content improvement
19+
- Easy custom plugin development
20+
21+
### 🤖 AI-Powered Generation
22+
- Multiple LLM provider support (OpenAI, Anthropic, local models)
23+
- Teaching style-aware prompt engineering
24+
- Streaming content generation
25+
26+
### 📚 Comprehensive Course Management
27+
- Multi-course support with weekly organization
28+
- Various content types (lectures, worksheets, quizzes, projects)
29+
- Progress tracking and version control
1230

1331
## Technology Stack
1432

15-
- **Backend**: FastHTML (Python + HTMX)
16-
- **Document Parsing**: python-docx, python-pptx
17-
- **AI Integration**: LangChain, OpenAI, Anthropic Claude
18-
- **Database**: SQLite
19-
- **Styling**: Tailwind CSS
20-
- **Deployment**: Docker
33+
- **Backend**: FastHTML (Python web framework with HTMX)
34+
- **Database**: SQLite with hybrid filesystem storage
35+
- **UI**: HTMX + Tailwind CSS (no complex JavaScript)
36+
- **AI Integration**: Pluggable LLM providers
37+
- **Testing**: pytest with FastHTML support
38+
- **Type Checking**: basedpyright
2139

2240
## Quick Start
2341

2442
```bash
25-
# Install dependencies
26-
pip install -r requirements.txt
43+
# Clone repository
44+
git clone https://github.com/yourusername/curriculum-curator.git
45+
cd curriculum-curator
46+
47+
# Create virtual environment
48+
python -m venv venv
49+
source venv/bin/activate # Windows: venv\Scripts\activate
50+
51+
# Install dependencies (using pyproject.toml)
52+
pip install -e .
53+
54+
# Configure environment (REQUIRED)
55+
cp .env.example .env
56+
# Edit .env and add your configuration:
57+
# - BREVO_API_KEY for email functionality
58+
# - SESSION_SECRET for security (generate with: openssl rand -hex 32)
59+
60+
# Initialize database
61+
python init_db.py
2762

2863
# Run development server
2964
python app.py
65+
# Or use the development script with auto-reload:
66+
python scripts/run_dev.py
3067

3168
# Open browser to http://localhost:5000
3269
```
3370

34-
## Architecture
71+
## 🔧 Configuration
72+
73+
The application requires configuration via environment variables. Copy `.env.example` to `.env`:
3574

75+
```bash
76+
cp .env.example .env
3677
```
37-
curriculum-curator-web/
38-
├── app.py # Main FastHTML application
39-
├── core/ # Business logic
40-
├── components/ # Reusable UI components
41-
├── static/ # CSS, JS, images
42-
└── uploads/ # Temporary file storage
78+
79+
### Required Configuration:
80+
- `BREVO_API_KEY`: For email verification and password reset (get free API key at https://www.brevo.com)
81+
- `SESSION_SECRET`: Strong secret for session security (generate with `openssl rand -hex 32`)
82+
- `APP_BASE_URL`: Your application URL (default: http://localhost:5000)
83+
84+
### Optional Configuration:
85+
- `SENDER_EMAIL`: Email address for sending emails (default: noreply@curtin.edu.au)
86+
- `DB_PATH`: Database file location (default: data/curriculum.db)
87+
88+
See [.env.example](.env.example) for all configuration options.
89+
90+
## Documentation
91+
92+
Comprehensive documentation is available in the `docs/` directory:
93+
94+
- [Documentation Index](docs/README.md)
95+
- [Getting Started Guide](docs/guides/getting-started.md)
96+
- [Architecture Overview](docs/concepts/architecture.md)
97+
- [API Reference](docs/api/README.md)
98+
- [Configuration Reference](docs/reference/configuration.md)
99+
100+
### Quick Links
101+
102+
**For Users:**
103+
- [Getting Started](docs/guides/getting-started.md)
104+
- [Teaching Styles Guide](docs/guides/teaching-styles.md)
105+
- [Deployment Guide](docs/guides/deployment.md)
106+
107+
**For Developers:**
108+
- [Development Guide](docs/development/DEVELOPMENT_GUIDE.md)
109+
- [Testing Guide](docs/development/TESTING_GUIDE.md)
110+
- [Plugin Development](docs/guides/custom-validators.md)
111+
- [Architecture Decision Records](docs/adr/)
112+
113+
**Reference:**
114+
- [Configuration Options](docs/reference/configuration.md)
115+
- [Plugin Catalog](docs/reference/plugin-catalog.md)
116+
- [Teaching Styles Reference](docs/reference/teaching-styles.md)
117+
118+
## Project Structure
119+
120+
```
121+
curriculum-curator/
122+
├── app.py # Main FastHTML application
123+
├── init_db.py # Database initialization script
124+
├── pyproject.toml # Python project configuration
125+
├── .env.example # Environment configuration template
126+
├── core/ # Core business logic
127+
│ ├── auth.py # Authentication system
128+
│ ├── email_service.py # Email integration
129+
│ ├── security.py # Security utilities
130+
│ ├── course_manager.py # Course management
131+
│ └── teaching_philosophy.py # Teaching style system
132+
├── scripts/ # Development & utility scripts
133+
│ ├── run_dev.py # Development server with auto-reload
134+
│ ├── run_tests.py # Test runner
135+
│ ├── check_types.py # Type checking
136+
│ └── test_plugins.py # Plugin system testing
137+
├── plugins/ # Plugin system
138+
│ ├── base.py # Base plugin classes
139+
│ ├── validators/ # Content validators
140+
│ └── remediators/ # Content improvers
141+
├── views/ # UI components
142+
│ ├── landing.py # Landing page
143+
│ ├── wizard_mode.py # Step-by-step interface
144+
│ └── expert_mode.py # Power user interface
145+
├── tests/ # Test suite
146+
├── docs/ # Comprehensive documentation
147+
│ ├── adr/ # Architecture Decision Records
148+
│ ├── guides/ # User and deployment guides
149+
│ └── SECURITY.md # Security overview
150+
└── data/ # Local data storage (gitignored)
43151
```
44152

45-
## Previous Version
153+
## Contributing
154+
155+
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
156+
157+
## License
158+
159+
[License information]
160+
161+
## Acknowledgments
46162

47-
The original Tauri/Rust desktop version is archived at: https://github.com/michael-borck/curriculum-curator/tree/18f4c024
163+
This project is a FastHTML-based reimplementation inspired by the original Tauri desktop application.

‎scripts/README.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Development Scripts
2+
3+
This directory contains utility scripts for development and testing.
4+
5+
## Available Scripts
6+
7+
### 🚀 run_dev.py
8+
Run the development server with auto-reload enabled:
9+
```bash
10+
python scripts/run_dev.py
11+
```
12+
- Starts server on http://localhost:5000
13+
- Auto-reloads on code changes
14+
- Shows detailed logging
15+
16+
### 🧪 run_tests.py
17+
Run the test suite with coverage:
18+
```bash
19+
python scripts/run_tests.py
20+
```
21+
- Runs all tests in the `tests/` directory
22+
- Generates coverage report in `htmlcov/`
23+
- Shows coverage summary in terminal
24+
25+
### 🔍 check_types.py
26+
Run type checking with basedpyright:
27+
```bash
28+
python scripts/check_types.py
29+
```
30+
- Checks type annotations
31+
- Reports type errors
32+
- Uses configuration from `pyrightconfig.json`
33+
34+
### 🔌 test_plugins.py
35+
Test the plugin system:
36+
```bash
37+
python scripts/test_plugins.py
38+
```
39+
- Loads all plugins
40+
- Runs plugin validation tests
41+
- Useful for plugin development
42+
43+
## Usage from Project Root
44+
45+
All scripts can be run from the project root:
46+
```bash
47+
# From curriculum-curator/ directory
48+
python scripts/run_dev.py
49+
python scripts/run_tests.py
50+
python scripts/check_types.py
51+
```
52+
53+
## Development Workflow
54+
55+
1. **Start development server**: `python scripts/run_dev.py`
56+
2. **Make changes** to code
57+
3. **Run tests**: `python scripts/run_tests.py`
58+
4. **Check types**: `python scripts/check_types.py`
59+
5. **Commit** when all checks pass

0 commit comments

Comments
 (0)