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 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 local development. Browser OAuth requests only identity scopes, then the backend uses the signed-in user's Forgejo identity from the encrypted session cookie for public repo reads and public issue replies. The backend must verify repositories are public before reading discussion data or writing comments.

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
```