The middleman between you and your units — built by UWA students, for UWA students.
stUwa is a web app that aggregates UWA unit information, degrees, student clubs, resources, benefits, account-backed study planning, public plan sharing, and student unit reviews into a single searchable interface. It eliminates the need to hunt across multiple university portals by surfacing everything in one place.
stUwa provides:
- Unit pages — credit points, level, semester, associated clubs, and curated learning resources (YouTube channels, platforms, textbooks)
- Degree pages — faculty, duration, and credit point requirements
- Club pages — descriptions, icons, and accent theming per club
- Student benefits — categorised discounts and perks available to UWA students
- Global search — AJAX search backed by a Flask JSON endpoint across all units, degrees, and clubs, with a no-JavaScript fallback page
- Study planner — an interactive planner for mapping units across semesters, tracking degree progress, syncing plans to an account, and sharing public plans
- Accounts — UWA student registration, login/logout, settings, and server-side persistence for planner and review data
- Unit reviews — student advice with rating, difficulty, workload, aggregate stats, owner delete controls, and a personal review list in settings
All content is stored as YAML files under data/, making it easy to add or update entries without touching application code.
The current app combines a YAML-backed catalogue with database-backed user features. Catalogue content remains easy to review in pull requests, while account data, saved plans, public plan visibility, and reviews are stored through SQLAlchemy.
| UWA ID | Name | GitHub username |
|---|---|---|
| 24357423 | Ben Masel | BenMasel |
| 24483753 | Kaushik Oril | Kaushik-Oril |
| 24518484 | Dhul Ratnayaka Ratnayaka Mudiyanselage | dhulrat |
| 24729724 | Hridayesh Sharma | Hri-Sh |
- Python 3.14+
uv— Python package and project manager
# 1. Clone the repository
git clone https://github.com/BenMasel/agile-web-dev.git
cd agile-web-dev
# 2. Install dependencies
uv sync
# 3. Create local environment config
cp .env.example .env
# 4. Apply database migrations
FLASK_APP=run.py uv run flask db upgrade
# 5. Start the development server
uv run python run.pyThe app will be available at http://localhost:5000.
The development server runs with
debug=True, which enables auto-reload on file changes and detailed error pages. Do not use this mode in production.
The project should be configured through environment variables rather than hard-coded secrets. The expected local setup is:
| Variable | Purpose |
|---|---|
SECRET_KEY |
Flask session and CSRF signing key |
DATABASE_URL |
SQLite database path for SQLAlchemy |
YOUTUBE_API_KEY |
Optional YouTube Data API key for resource search |
Copy .env.example to .env and replace the placeholder values for local development.
The project includes a Flask-Migrate/Alembic migration baseline under migrations/.
# Apply database migrations
FLASK_APP=run.py uv run flask db upgrade
# Create a new migration after model changes
FLASK_APP=run.py uv run flask db migrate -m "Describe the model change"For development convenience, the app also calls SQLAlchemy create_all() during startup so a fresh local SQLite database is created automatically if migrations have not been run yet.
The automated test suite uses pytest for route, model, data validation, authentication, planner, review, and public plan coverage.
# Install dependencies
uv sync
# Run tests
uv run pytest
# Validate YAML catalogue data
uv run python scripts/validate_data.py
# Check major pages render valid core HTML through Flask
uv run python scripts/check_rendered_pages.pyThe repository also includes a GitHub Actions workflow at .github/workflows/tests.yml that installs dependencies with uv sync and runs uv run pytest on pushes and pull requests.
The repository also includes Selenium live-browser tests for the main user journeys. The tests start their own live Flask server, so they can be run directly:
uv run pytest tests/seleniumInstall the matching browser driver for the browser used by the Selenium tests. For Chrome-based tests, use a Chrome/Chromium version with a compatible ChromeDriver available on PATH; for Firefox-based tests, use GeckoDriver.
agile-web-dev/
├── app/
│ ├── __init__.py # Application factory (create_app)
│ ├── routes.py # All route handlers and YAML data helpers
│ ├── docs_bp.py # Docs blueprint — serves docs/ as /docs/<slug>
│ ├── models.py # SQLAlchemy models for users, plans, reviews, preferences
│ ├── forms.py # Flask-WTF forms and validators
│ ├── db.py # Legacy SQLite helper retained for compatibility
│ ├── templates/ # Jinja2 HTML templates
│ │ ├── base.html
│ │ ├── home.html
│ │ ├── benefits.html
│ │ ├── resources.html
│ │ ├── docs/ # Docs page template
│ │ ├── unit/
│ │ ├── degree/
│ │ ├── club/
│ │ └── plans/ # Public study plan pages
│ └── static/ # CSS, JS, icons, and images
│ ├── css/
│ ├── js/
│ ├── icons/
│ └── img/
├── data/ # YAML content files (source of truth)
│ ├── units/ # One .yaml file per unit (e.g. CITS1001.yaml)
│ ├── degrees/ # One .yaml file per degree
│ ├── clubs/ # One .yaml file per club
│ ├── benefits/ # Student benefits data
│ └── schemas/ # JSON schemas for validating YAML files
├── docs/ # Markdown documentation (rendered at /docs)
│ └── overview.md # Project overview, goals, philosophy, roadmap
├── run.py # Entry point — creates and runs the Flask app
├── pyproject.toml # Project metadata and dependencies
└── uv.lock # Locked dependency versions
| Tool | Purpose |
|---|---|
| Python 3.14 | Language runtime |
| Flask | Web framework and routing |
| Jinja2 | Server-side HTML templating (bundled with Flask) |
| PyYAML | Parsing YAML content files |
| jsonschema | Validating YAML data against schemas |
| Python-Markdown | Rendering docs/*.md files as HTML at /docs |
| uv | Dependency management and virtual environment |
| AJAX search | Server-scored catalogue search with a no-JavaScript fallback |
| Highlight.js | Syntax highlighting for code blocks in docs (CDN) |
| SQLite | Lightweight development database |
| Flask-SQLAlchemy | ORM for account, planner, review, and preference models |
| Flask-Login | User session management |
| Flask-WTF | Forms and CSRF protection |
Create a new .md file in docs/ — it will automatically appear in the sidebar at /docs with no further configuration needed. The first # H1 in the file is used as the page title.