diff --git a/README.md b/README.md
index 5ea9c35..8c13f79 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,49 @@
-# jellyfin-lessons
+# Jellyfin Lessons Plugin
 
-Jellyfin plugin for homeschool lesson plans — Typst-based content with embedded media playback
\ No newline at end of file
+A Jellyfin plugin that delivers homeschool lesson plans with embedded media playback. Content authored in Typst, managed via a web admin UI, displayed natively inside Jellyfin on any client (Fire TV, web, mobile).
+
+## Architecture
+
+```
+~/vault/lessons/                    ← Typst source files (author here)
+    └── grade-N/
+        └── subject/
+            └── lesson-name.typ
+
+        ↓ admin UI reads/writes lesson metadata
+
+~/.local/share/jellyfin-lessons/    ← Lessons DB + compiled HTML cache
+        ↓ Jellyfin plugin reads
+
+Jellyfin "Lessons" tab              ← Plugin renders lesson HTML + media player
+```
+
+## Components
+
+1. **Jellyfin Plugin** (C# / .NET 9) — Registers a "Lessons" page in Jellyfin, reads lesson data from the store, renders Typst-compiled HTML, and embeds the native Jellyfin media player for linked items.
+
+2. **Lesson Data Store** — SQLite database mapping lesson metadata (title, grade, subject, date, jellyfin item IDs) to compiled HTML output. Shared between the plugin and admin UI.
+
+3. **Typst Lesson Template** — A `.typ` template with frontmatter conventions for lesson metadata and embedded Jellyfin media references. Compiles to HTML.
+
+4. **Web Admin UI** — Simple web interface (served from n97) for creating, editing, and previewing lessons. Writes to the same SQLite store the plugin reads from.
+
+5. **Nix Flake** — Builds the plugin DLL, packages it for Jellyfin, provides a dev shell with dotnet-sdk + typst.
+
+## End State (Outcome Engineering)
+
+- Open Jellyfin on any device → see "Lessons" in the nav
+- Click a lesson → read the content → click play on embedded media → Jellyfin plays it
+- Author lessons by writing `.typ` files (with a web UI option)
+- Everything works fully offline on the homelab
+- One `nix build` produces the plugin
+
+## Development
+
+```bash
+nix develop    # dotnet-sdk, typst, node (for admin UI)
+```
+
+## License
+
+MIT