The Philosophy
TyloPlanner was born out of a frustration with modern productivity apps. Most planners demand expensive subscriptions, trap your data in their cloud ecosystems, and are incredibly bloated. TyloPlanner takes the opposite approach: it is deliberately small, dependency-light, and entirely self-hosted. You own your server, you own your database.
The entire codebase is designed so that a student can read all of it in an afternoon and bend it to their needs.
Core Architecture
The application relies on a simple, robust stack without any complex frontend build steps (like Webpack or Vite) or heavy ORMs.
Python & Flask
The backend is a fast, lightweight Python Flask server driving generic REST APIs.
SQLite3
Zero-configuration database. Everything lives in one single file on your machine.
Vanilla JS
Frontend rendering uses pure ES modules and native DOM manipulation. No React, no Vue.
Docker
One command deployment. A single container runs the server and background jobs.
How it works
When you open TyloPlanner, the frontend (`app.js`) fetches the full application state (`GET /api/state`) and keeps it in a global state object. The UI is then rendered synchronously. When you edit a note or check off a habit, changes are pushed via standard API calls (`POST`, `PUT`, `DELETE`). The backend enforces a strict whitelist of columns to ensure security and simplicity.
Offline Mode & Sync Queue
TyloPlanner functions flawlessly even when you lose internet connection on your phone or laptop. It achieves this using modern browser features:
- Service Workers cache all HTML, CSS, JS, and image assets so the app loads instantly offline.
- IndexedDB acts as a local cache (`tyloplanner_offline`). It stores the latest version of your application state.
- Mutation Queuing: If you make a change (like ticking off a task) while offline, TyloPlanner intercepts the API request and queues it locally in IndexedDB. As soon as the network connection is restored, the client automatically replays all queued mutations to the server sequentially, ensuring zero data loss.
Background Scheduler & Automation
TyloPlanner isn't just a passive dashboard; it works for you in the background. A dedicated background daemon thread (`scheduler.py`) ticks every minute to handle automated tasks:
- Calendar Auto-Sync: Pulls in standard iCal URLs from your university or Google Calendar and parses locations and timezones.
- Web Push Notifications: Pushes morning agendas (overdue tasks, today's schedule) and evening habit nudges directly to your phone using native browser VAPID Web Push or Ntfy.
- Nightly Backups: Automatically dumps the SQLite database to a backup file every night so you never lose your data.
Security
Even though it's built to be simple, security is not compromised. TyloPlanner features session-based authentication, an optional TOTP Two-Factor Authentication (2FA) flow, and parameterized SQL queries to prevent injections. All endpoints require a valid session cookie (or secret feed key).