From ee531c55f3fdf0d4c10f8cc37f42b7a40580a404 Mon Sep 17 00:00:00 2001 From: Fizzlepoof Date: Sat, 16 May 2026 20:33:31 +0000 Subject: [PATCH] Clarify Doris stack README purpose and runtime --- home/doris-dashboard/README.md | 70 +++++++++++++++++++++++--------- home/doris-schoolhouse/README.md | 63 ++++++++++++++++++++++------ 2 files changed, 101 insertions(+), 32 deletions(-) diff --git a/home/doris-dashboard/README.md b/home/doris-dashboard/README.md index 15beec4..78bc1b4 100644 --- a/home/doris-dashboard/README.md +++ b/home/doris-dashboard/README.md @@ -1,6 +1,56 @@ # Doris Dashboard -Local static homepage for John’s morning briefing and peek-anytime news dashboard. +Local homepage for John's briefing, glanceable status, and "what matters right now" view. + +## What it is + +Doris Dashboard is the quiet front page for John's local information stack on NOMAD. It is not a general website and it is not meant to be another feed reader with a fresh coat of paint. It exists to turn Doris Digest output and a few homelab/task signals into one page John can open for a fast read. + +The dashboard is meant to answer: + +- what is worth looking at this morning +- what local or homelab signals need attention +- what chores or Paperless follow-ups are still hanging around +- what topics are surfacing too often and should be tuned down + +## Why it exists + +Without this stack, the raw inputs are noisy: + +- Doris Digest candidates are too broad on their own +- Donetick and Paperless are useful but fragmented +- local weather/sky/homelab signals live in separate places + +The dashboard turns that into one opinionated, local-only page that Doris can tune over time. + +## Runtime model + +- **Repo source:** `/home/fizzlepoof/repos/truenas-stacks/home/doris-dashboard` +- **Live runtime:** `/opt/doris-dashboard` +- **Generated page:** `/opt/doris-dashboard/public/index.html` +- **LAN URL:** `http://10.5.1.16:8787/` +- **Exposure rule:** local-only unless John explicitly asks otherwise + +## What it shows + +- top briefing cards from Doris Digest candidates +- space / homelab / local / other signal lanes +- an experimental `New to You` lane for off-profile category sampling +- Donetick tasks +- Paperless review queue items +- weather, sky, and homelab pulse cards +- lightweight stats about candidate/source mix + +## How it works + +- `bin/generate_dashboard.py` reads Doris Digest candidates plus a few local/runtime data files. +- It scores, deduplicates, and groups stories into dashboard sections. +- It writes generated JSON artifacts under `data/` and the final static page under `public/`. +- `bin/dashboard_server.py` serves the page and handles interactive actions like topic feedback and Paperless review state. + +That means the dashboard is static-looking for the reader, but still has enough local interactivity for feedback and review flows. + +## Live paths Live runtime path: @@ -8,30 +58,12 @@ Live runtime path: /opt/doris-dashboard ``` -Source path in the homelab repo: - -```bash -/home/fizzlepoof/repos/truenas-stacks/home/doris-dashboard -``` - Generated page: ```bash /opt/doris-dashboard/public/index.html ``` -## What it shows - -- Morning briefing with fleshed-out cards -- Today panel for calendar placeholders -- To-do panel for Donetick/to-do placeholders -- Notes panel -- Sky / Space -- Homelab / Smart Home / Ham Radio -- Local news -- Other signal -- Source/candidate stats - ## Generate manually ```bash diff --git a/home/doris-schoolhouse/README.md b/home/doris-schoolhouse/README.md index b5258a9..54cb531 100644 --- a/home/doris-schoolhouse/README.md +++ b/home/doris-schoolhouse/README.md @@ -1,10 +1,21 @@ # Doris Schoolhouse -Desktop-first local web app for school intake, recordings, D2L sync, and Paperless linkage. +Desktop-first school operations app for John. -## Purpose +## What it is -This app gives John a fast local UI to: +Doris Schoolhouse is the front door for John's college workflow. It pulls scattered school chores into one place so Doris can handle intake, metadata, archiving, and later grade follow-up without bouncing between D2L, file uploads, recordings, and Paperless by hand. + +In plain English, this stack exists to answer: + +- what classwork is due +- where a submission or recording should be filed +- how that item should be archived and tagged +- whether grading/comments later made it back onto the archived record + +## What it does + +Schoolhouse gives John a local UI to: - upload assignment turn-ins, with programming-class source files bundled into one archived submission artifact - upload class recordings @@ -13,25 +24,51 @@ This app gives John a fast local UI to: - sync classes/assignments/grades/comments from D2L - archive submissions/transcripts/summaries in Paperless -## Source vs runtime +## Why it exists + +The point is not just "another web app." The point is to make school intake boring and repeatable. + +- D2L is the source for classes, assignments, grades, and comments. +- Schoolhouse is the operational layer where uploads, recordings, and metadata are managed. +- Paperless is the long-term archive for receipts, transcripts, summaries, and school documents. +- n8n handles the workflow glue between intake events and downstream processing. + +That split keeps John from doing the same clerical nonsense over and over, and gives Doris one consistent place to reason about schoolwork. + +## Runtime model - **Repo source:** `home/doris-schoolhouse` -- **Expected live NOMAD runtime:** `/opt/doris-schoolhouse` +- **Live NOMAD runtime:** `/opt/doris-schoolhouse` +- **Published app port:** `8091` +- **Public path:** `schoolhouse.paccoco.com` behind Pangolin OAuth +- **Storage:** shared Postgres in production, JSON fallback for local iteration +- **Archive path:** Paperless + n8n school workflows -Do not run production from an agent workspace. +Do not run production from an agent workspace. Repo source is for editing; `/opt/doris-schoolhouse` is the live runtime. -## Stack +## How it works - FastAPI - Jinja2 templates - shared Postgres -- Pangolin network +- Pangolin-authenticated public route - existing Paperless and n8n school workflows -- container build now includes Python deps + `ffmpeg` for recording conversion +- bundled `ffmpeg` for recording conversion inside the container + +Typical flow: + +1. D2L data is synced into Schoolhouse. +2. John uploads an assignment or recording through Schoolhouse. +3. Schoolhouse normalizes the intake payload and keeps local/runtime state. +4. n8n receives the handoff and pushes the right artifacts into Paperless. +5. Paperless becomes the durable archive. +6. Later grade/comment updates can be reflected back onto the archived record. + +Programming-class uploads get special handling: multiple source files are bundled into one canonical source archive, with manifest and receipt/listing artifacts so the repo of what was turned in stays coherent. ## Current state -The app is live on NOMAD at `/opt/doris-schoolhouse` and uses shared Postgres in production. +Schoolhouse is live on NOMAD and already covers the real workflow, not just a mockup. For local iteration, the source tree still supports a JSON-backed mode: @@ -49,11 +86,11 @@ Production runtime uses shared Postgres plus Paperless/n8n integration. `SCHOOLHOUSE_STORAGE_BACKEND=auto` prefers Postgres when psycopg and a PostgreSQL DSN are available, and falls back to JSON state for local iteration. -Repo contents still include: -- route handlers and templates +This repo directory contains: +- the FastAPI app and templates - schema/bootstrap helpers - compose/env examples -- D2L / Paperless / n8n integration code +- D2L, Paperless, and n8n integration code ## Layout