Robot-U/robot-u-site
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
robot-u-site/AGENTS.md

3.7 KiB
Raw Blame History

Robot U Site Agent Guide

Purpose

This repository contains the Robot U community site.

It is a thin application layer over Forgejo:

  • Forgejo is the source of truth for authentication, public content repos, and issue-backed discussions.
  • This app provides the web UI, course/lesson browsing, markdown rendering, and ICS calendar ingestion.
  • The current live Forgejo instance is https://aksal.cloud.

Stack

  • Backend: FastAPI
  • Frontend: Preact + TypeScript + Vite
  • Python tooling: uv, ruff
  • Frontend tooling: bun, Biome

Important Files

  • app.py: FastAPI app and SPA/static serving
  • live_prototype.py: live payload assembly for courses, lessons, discussions, and events
  • forgejo_client.py: Forgejo API client
  • calendar_feeds.py: ICS/webcal feed loading and parsing
  • settings.py: env-driven runtime settings
  • frontend/src/App.tsx: client routes and page composition
  • frontend/src/MarkdownContent.tsx: safe markdown renderer used in lessons and discussions
  • scripts/start.sh: main startup command for local runs

Repo Layout Notes

  • The root repository is the site application.
  • examples/quadrature-encoder-course/ is a separate nested git repo used as sample content. It is intentionally ignored by the root repo and should stay that way.

First-Time Setup

Python

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

Frontend

cd frontend
~/.bun/bin/bun install

Environment

Runtime configuration is loaded from shell env, then .env, then .env.local through scripts/start.sh.

Recommended local flow:

cp .env.example .env

Useful variables:

  • FORGEJO_BASE_URL=https://aksal.cloud
  • FORGEJO_TOKEN=...
  • CALENDAR_FEED_URLS=webcal://...
  • HOST=0.0.0.0
  • PORT=8800

Notes:

  • FORGEJO_TOKEN is required for live repo and discussion reads on aksal.cloud.
  • CALENDAR_FEED_URLS is optional and accepts comma-separated webcal:// or https:// ICS feeds.
  • Do not commit .env or .env.local.

Main Start Command

Use this for the normal local app flow:

./scripts/start.sh

What it does:

  1. Loads .env and .env.local if present.
  2. Builds the frontend with bun.
  3. Starts FastAPI with uvicorn.

Override host/port when needed:

HOST=0.0.0.0 PORT=8800 ./scripts/start.sh

Development Commands

Backend only

.venv/bin/python -m uvicorn app:app --reload

Frontend only

cd frontend
~/.bun/bin/bun run dev

Frontend production build

cd frontend
~/.bun/bin/bun run build

Quality Checks

Run both before pushing:

./scripts/check_python_quality.sh
./scripts/check_frontend_quality.sh

Product/Data Model Background

  • Public non-fork repos are scanned.
  • A repo with /lessons/ is treated as a course repo.
  • A repo with /blogs/ is treated as a post repo.
  • Lessons are discovered from lessons/<chapter>/<lesson>/.
  • Each lesson folder is expected to contain one markdown file plus optional assets.
  • Frontmatter is used when present for title and summary.
  • Discussions are loaded from Forgejo issues and comments.
  • Calendar events are loaded from ICS feeds, not managed in-app.

UI Expectations

  • The UI should not expose Forgejo as a user-facing implementation detail unless necessary for debugging.
  • Course cards should open course pages.
  • Lesson rows should open lesson pages.
  • Discussion pages should focus on one thread at a time.
  • Markdown should render as readable content, not raw source.

Push Workflow

The site source repo currently lives at:

  • git@aksal.cloud:Robot-U/robot-u-site.git

Typical push flow:

git status
git add ...
git commit -m "..."
git push origin main