Personal teaching reporting tool

TypeScript · Node.js · SQLite · external integrations

I designed, developed, and maintain this personal tool. I'm its only developer and its only user, and I've evolved it over six months alongside my software specialization at EAFIT. It connects my calendar, teaching notes, AI-assisted session summaries, and the dashboard where teaching hours are reported, so that reporting takes less of my time and leaves more for teaching.

Where it fits

I run it from the command line. It reads scheduled sessions and notes, compares them with what the dashboard has recorded, shows me the differences, and applies only the changes I approve.

System context The teacher runs commands and reviews changes in the reporting tool. The tool reads sessions from Google Calendar and notes from Notion, reads dashboard records and applies reviewed changes to the dashboard, requests summary drafts from an AI provider, and sends hours notices through a push notification service back to the teacher. Teacher (operator) Reporting tool CLI + SQLite runs, reviews Google Calendar reads sessions Notion reads notes Hours dashboard reads; applies reviewed changes AI provider drafts summaries Push service sends hours notices
Simplified system context. The tool also has audio capture and transcription workflows, left out here to keep the focus on reporting. Hours notices reach the teacher through the push service.

Inside the application

It is a modular monolith: one Node.js codebase and one SQLite database, divided into capability modules that each own their state. The command line adapters call operations (discover, reconcile, update), which use the modules through their public interfaces. A separate scheduled job, run by GitHub Actions, checks remaining hours.

Application components Within the application, command line adapters call operations, operations call modules, and modules use a shared SQLite database and reach the calendar, Notion, dashboard, and AI provider. A GitHub Actions schedule runs the hours-alert job, which reads dashboard hours, stores alert state, and sends push notifications. Reporting application CLI adapters args, prompts, output Operations discover, reconcile Modules sessions, notes, AI SQLite shared database Calendar · Notion · dashboard · AI provider GitHub Actions schedule Hours-alert job Dashboard hours (read) Alert state (stored) Push notifications (sent)
Simplified component view of the reporting workflow. Edges show the main direction of calls.

Decisions worth explaining

Reconcile, then review
Calendar-backed sessions, notes, and dashboard records are compared, and discrepancies are shown for review instead of being silently corrected. I decide what changes.
Writes preview unless applied
Each command that can change the dashboard shows a preview unless I pass --apply. The combined pipeline goes the other way and refuses to start without it. The dashboard's HTTP client also checks every non-GET request against a mutation policy before it reaches the server.
Generated summaries don't overwrite my edits
AI-assisted summaries are drafts that are stored for later reporting. When I regenerate, summaries I've edited or imported are preserved.
Alerts that don't repeat themselves
The hours-alert job stores its warning state, so a low balance produces one notification rather than one per run. A balance that goes up is treated as an observed change, not as proof of payment.

Keeping it maintainable as it grew

Result

I use it for my own reporting. It takes less of my time, the reporting is better because the tool makes it easier, and I've been able to spend the time saved on teaching. I haven't measured the time saved and it has no other users, so I don't claim numbers or wider adoption.

The source is in a private repository. I'm happy to walk through the code and the architecture decision records on a call.