robot-u-site/README.md

# Robot U Site Prototype

Thin frontend layer over Forgejo for community learning content, discussions, and events.

## Stack

- FastAPI backend
- Preact + TypeScript frontend built with Vite
- `bun` for frontend tooling
- `uv` + `ruff` for Python checks

## Local Development

### Backend

```bash
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/python -m uvicorn app:app --reload
```

### Start App

Build the frontend and then serve the app from FastAPI:

```bash
./scripts/start.sh
```

The script automatically loads `.env` and `.env.local` if present.

Optional runtime overrides:

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

Optional live Forgejo configuration:

```bash
export APP_BASE_URL="http://kacper-dev-pod:8800"
export AUTH_SECRET_KEY="$(openssl rand -hex 32)"
export FORGEJO_BASE_URL="https://aksal.cloud"
export FORGEJO_OAUTH_CLIENT_ID="your-forgejo-oauth-client-id"
export FORGEJO_OAUTH_CLIENT_SECRET="your-forgejo-oauth-client-secret"
export FORGEJO_OAUTH_SCOPES="openid profile"
export FORGEJO_GENERAL_DISCUSSION_REPO="Robot-U/general_forum"
export FORGEJO_WEBHOOK_SECRET="shared-webhook-secret"
export FORGEJO_CACHE_TTL_SECONDS="60.0"
export CALENDAR_FEED_URLS="webcal://example.com/calendar.ics,https://example.com/other.ics"
```

`APP_BASE_URL` must match the URL you use in the browser. Create the OAuth app in Forgejo with this redirect URI:

```text
http://kacper-dev-pod:8800/api/auth/forgejo/callback
```

`AUTH_SECRET_KEY` is required for Forgejo OAuth sign-in. It encrypts the `HttpOnly` browser session cookie that carries the signed-in user's Forgejo token and identity. Set `AUTH_COOKIE_SECURE=true` when serving over HTTPS.

`FORGEJO_TOKEN` is optional. When set, it is a read fallback for the public content cache. Browser OAuth requests only identity scopes, then the backend uses the signed-in user's Forgejo identity from the encrypted session cookie for public discussion creation and replies. The backend must verify repositories are public before reading discussion data or writing issues/comments.

`FORGEJO_CACHE_TTL_SECONDS` controls how long the server reuses the public Forgejo content scan for `/api/prototype`. Set it to `0` to disable caching while debugging discovery behavior.

`FORGEJO_GENERAL_DISCUSSION_REPO` should point at the public `owner/repo` used for general discussion threads. Post- and lesson-linked discussions are created in the same repo as the content being discussed.

`FORGEJO_WEBHOOK_SECRET` is optional but recommended. Configure Forgejo webhooks to POST to `/api/forgejo/webhook`; matching webhook events invalidate the public content cache and notify open browsers over `/api/events/stream`.

Or put those values in `.env`:

```bash
cp .env.example .env
```

Use the site `Sign in` button for Forgejo OAuth, or query the API directly with:

```bash
curl -H "Authorization: token your-forgejo-api-token" http://127.0.0.1:8800/api/prototype
```

### Frontend

```bash
cd frontend
~/.bun/bin/bun install
~/.bun/bin/bun run dev
```

### Quality Checks

```bash
./scripts/check_python_quality.sh
./scripts/check_frontend_quality.sh
```