Mister Wiz Report Compiler

A Python tool that reads teacher-filled CSV data and generates print-ready HTML reports for every student and class at Mister Wiz English school.

---

What it does

Teachers fill in two CSV files once per reporting period. Running python compiler.py produces:

Output	One file per	Content
{TURMA}_{Student}_report.html	Student	Individual A4 landscape report card
{TURMA}_class_diagnostic.html	Class	Full class diagnostic (profiles, skill charts, indices, reinforcement pages)

All outputs are self-contained HTML — open in any browser and Print → Save as PDF.

---

Tech stack

• Python 3.8+ — CLI report compiler; optional Flask web dashboard
• Flask + Gunicorn — teacher dashboard (deployed on Railway)
• PostgreSQL (optional) — persistent student/lesson data via SQLAlchemy
• Jinja2 — HTML templating
• Inline SVG — radar/pentagon charts and attendance pie charts (no JS, no external charting libs)
• CSS @page — A4 landscape print layout
• Brand CSS + Carlito — identity tokens in static/css/brand.css; official lockups in static/img/
• pytest — unit and integration tests

---

Project structure

mister-wiz-report-compiler/
├── compiler.py              # Main script — reads CSVs, renders templates, writes output/
├── app.py                   # Flask web dashboard
├── railway.json             # Railway deploy config (gunicorn)
├── requirements.txt
├── static/
│   ├── css/brand.css        # Palette, type, CSS variables
│   ├── fonts/               # Carlito (SIL OFL) — Calibri-compatible UI font
│   └── img/                 # Official logos + icon sprite (icons.svg)
├── templates/               # Print report HTML (Jinja2)
├── web_templates/           # Dashboard HTML (Flask)
├── docs/brand.md            # Logo, colour, and type rules for this app
├── data/                    # Sample / local CSV data
└── output/                  # Generated HTML files (git-ignored)

---

Brand & UI

The dashboard and print reports follow the Mister Wiz Brand & Identity Guide. Tokens live in static/css/brand.css; usage rules are in docs/brand.md.

Token	Hex	Use
Primary purple	#792D83	Headings, buttons, table headers
Dark purple	#5A1A64	Secondary text, labels
Plum	#2D1040	Body text, login gradient
Lavender	#F0E6F3	Sidebar, soft fills, row banding
Gold / gold accent	#EFD27E / #EBB22E	Emphasis, dividers, active-nav mark
Green / red	#2C7A3F / #E24B4A	Success / error only

Logos: official MISTER WIZ wordmark (black + purple figure) on white or lavender; white knockout on plum/purple (never invert). Aspect ratio ~6.7 : 1 — do not stretch. Favicon is the Wiz figure.

Icons: Mister Wiz Icon Library in static/img/icons.svg — 24 grid, 2 px round stroke, purple on light / white on dark. Do not fill, rotate, or mix with emoji.

Type: Carlito in the web UI (Calibri in Word). Do not introduce other blues or greens, and do not use navy (#1B1464) outside the logo.

---

How to run

CLI report generation:

python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
python compiler.py
# -> output/ now contains all student reports and class diagnostics

Web dashboard (easiest local test):

cp .env.example .env
# Edit .env: SUPERADMIN_EMAIL and SUPERADMIN_PASSWORD

chmod +x scripts/dev.sh
./scripts/dev.sh
# Prints your login email and starts the server (uses 5001 if macOS blocks 5000)
# Open the URL shown in the terminal, e.g. http://127.0.0.1:5001/login

Quick automated journey check (no browser):

.venv/bin/python scripts/smoke_journey.py

Manual alternative:

python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
python app.py

To run the test battery:

. .venv/bin/activate
pytest -q

Database mode (optional)

The app can run in two storage modes:

• CSV mode (default): reads/writes data/students.csv and data/lessons.csv.
• Database mode: enabled when DATABASE_URL is set.

When DATABASE_URL exists, students and lessons are stored in SQL tables and the upload flow writes validated CSV data directly to the database.

For Railway PostgreSQL:

1. Create a PostgreSQL service in Railway.
2. Copy DATABASE_URL from the PostgreSQL service variables.
3. Set DATABASE_URL on your Railway web service (Variables → reference the Postgres service).
4. Redeploy the app.

Notes:

• If your URL starts with postgres://, the app auto-normalizes it and adds sslmode=require (required on Railway).
• On the web service, reference Postgres DATABASE_URL (private URL), not the public proxy URL unless you know you need it.
• Tables are created automatically on startup.
• After deploy, open /health/db — connected should be true.

---

Student photos

On Alunos → Editar, upload a JPG, PNG or WebP (up to 700 KB). The photo appears as the student's avatar in the list and in the header of every report generated or previewed afterwards. Students without a photo show their initials.

Photos are keyed by the same pseudonymous student_id as snapshots (hash of turma|student_name), so the photo store holds no names. They live in the student_photo_rows table in database mode, or data/student_photos.json (git-ignored) in CSV mode. Renaming, transferring or deleting a student moves or removes the photo, and teachers can only reach photos of their own students.

Security headers

Every response carries a Content-Security-Policy (same-origin only; inline scripts and styles allowed because the templates use them), X-Content-Type-Options, X-Frame-Options, Referrer-Policy and Permissions-Policy. HSTS is added on HTTPS requests in production.

---

Data model

data/students.csv

One row per student. All score fields are integers 1–5.

This is the beginning of the README. Read the rest at the original. Read the full README ↗