# {APP_NAME}

> Generated by [Supero](https://supero.dev) on {GENERATED_DATE}
> SDK version: `{SDK_VERSION}`

A full-stack application built on the Supero platform — schema-driven, multi-tenant,
and zero-build. Runs entirely from CDN with no Node.js or npm required.

---

## Quick Start

Choose your preferred runtime — **both are equally supported**:

### Option A: Direct Python

```bash
./run.sh            # Linux/Mac
run.bat             # Windows
```

**Requires:** Python 3.9+

### Option B: Docker

```bash
docker compose up
```

**Requires:** Docker 20.10+ and Docker Compose v2

---

Either option opens at **http://localhost:{PORT}**

**Login with seed credentials:**

| Field | Value |
|-------|-------|
| Domain | `{DOMAIN}` |
| Email | `{ADMIN_EMAIL}` |
| Password | See `setup.py` → `USERS` list |

Additional users (if any) are defined in `setup.py`.

---

## Your Configuration

| Setting | Value |
|---------|-------|
| App name | `{APP_NAME}` |
| Domain | `{DOMAIN}` |
| Project | `{PROJECT}` |
| Default tenant | `{TENANT}` |
| Port | `{PORT}` |
| SDK version | `{SDK_VERSION}` |
| Generated | `{GENERATED_DATE}` |

To change any of these, edit `.env` and re-run `./run.sh` or rebuild your
Docker container.

---

## Project Structure

```
.
├── README.md                   ← You are here
├── CLAUDE.md                   ← Context for Claude Code
├── .cursorrules                ← Context for Cursor (copy of CLAUDE.md)
├── .windsurfrules              ← Context for Windsurf (copy of CLAUDE.md)
├── run.sh / run.bat            ← Start script (bootstrap + serve)
├── Dockerfile                  ← Container image
├── docker-compose.yml          ← Local dev + simple prod
├── .env                        ← Domain, project, API key
│
├── schemas.py                  ← Data models (edit this)
├── setup.py                    ← Seed data, users, workflows (edit this)
├── config.py                   ← Python configuration
├── crud_tests.py               ← Auto-generated smoke tests
├── supero_*.whl                ← Tenant SDK (built during bootstrap)
│
└── ui/
    ├── app.js                  ← YOUR UI code (edit this)
    ├── supero-ui.js            ← Platform library (DO NOT MODIFY)
    ├── index.html              ← HTML shell (auto-generated)
    ├── config.js               ← Runtime config (auto-generated)
    └── server.py               ← Dev server + API proxy (auto-generated)
```

### File roles at a glance

| File | Edit it? | Purpose |
|------|----------|---------|
| `schemas.py` | Yes | Define your data model |
| `setup.py` | Yes | Seed data, users, workflows, policies |
| `ui/app.js` | Yes | All custom UI code goes here |
| `ui/supero-ui.js` | No | Platform library (overwritten on every run) |
| `ui/index.html` | No | Auto-generated by the CLI |
| `ui/config.js` | No | Auto-generated on every run |
| `ui/server.py` | No | Auto-generated by the CLI |
| `supero_*.whl` | No | Tenant SDK wheel, rebuilt during bootstrap |
| `crud_tests.py` | No | Auto-generated smoke tests |
| `.env` | Yes | Credentials and environment config |
| `Dockerfile` | Rarely | Only if you need extra system deps |
| `docker-compose.yml` | Yes | Customize ports, volumes, env vars |

---

## Prerequisites

Pick one of:

**For Python workflow:**
- Python 3.9+
- A Supero account — [get one at supero.dev](https://supero.dev)

**For Docker workflow:**
- Docker 20.10+ with Docker Compose v2
- A Supero account

**Always required:**
- A modern browser (Chrome, Firefox, Safari, Edge)

No Node.js, no npm, no webpack, no build step. React, Tailwind, and all UI
dependencies load from CDN.

---

## Configuration (.env)

```bash
SUPERO_DOMAIN={DOMAIN}
SUPERO_PROJECT={PROJECT}
SUPERO_API_KEY=ak_...
SUPERO_DEFAULT_TENANT={TENANT}
PORT={PORT}
```

The same `.env` file works for both Python and Docker workflows —
`docker-compose.yml` reads it automatically via `env_file`.

**Security note:** Never commit `.env` to version control.

---

## Running Locally

### With Python

```bash
./run.sh
```

The `run.sh` script invokes `python -m supero.cli`, which bootstraps your
app against the Supero platform. Each `./run.sh` run:

1. **Validates** project files (`schemas.py`, `setup.py`, `config.py`)
2. **Creates** a virtual environment at `.venv/`
3. **Installs** the Supero SDK
4. **Generates** `ui/index.html`, `ui/config.js`, `ui/server.py`
5. **Downloads** `ui/supero-ui.js` from CDN
6. **Bootstraps** the domain, schemas, users, workflows, and seed data via `setup.py`
7. **Runs** CRUD smoke tests against every schema
8. **Starts** the web server on port `{PORT}`

**Stopping the server:** Press `Ctrl+C` in the terminal running `run.sh`.

### With Docker

```bash
docker compose up              # foreground
docker compose up -d           # background (detached)
docker compose logs -f         # tail logs
docker compose restart         # restart the container
docker compose down            # stop and remove container
```

The container runs the same `./run.sh` internally (when the default `CMD`
is in place), so each container start or restart re-runs the full bootstrap
sequence above. Your source files (`schemas.py`, `setup.py`, `config.py`,
`ui/`) are mounted as volumes in `docker-compose.yml`, so **changes are
reflected immediately** — no image rebuild needed for code edits.

**Rebuilding the image** is only needed if you change `Dockerfile` or
`requirements.txt`:

```bash
docker compose build --no-cache
docker compose up
```

### Useful CLI flags

```bash
./run.sh --setup-only       # Bootstrap without starting server
./run.sh --server-only      # Start server, skip bootstrap
./run.sh --reset            # Re-upload schemas and re-run bootstrap
./run.sh --docker           # Build and run with Docker Compose
./run.sh --no-interactive   # Use .env values without prompting
./run.sh --verbose          # Show detailed logs
./run.sh --skip-tests       # Skip CRUD smoke tests
```

### Bootstrap is idempotent

Re-running `./run.sh`, rebuilding the Docker image, or restarting the
container is **always safe**. The bootstrap step syncs schema and seed
data changes without duplicating records.

---

## Developing Your App

### The golden rule

> **All custom code goes in `ui/app.js`.** Never modify `supero-ui.js` — it
> gets overwritten whenever the SDK updates.

### Common extension patterns

| Goal | Hook | Complexity |
|------|------|------------|
| Add dashboard KPIs/charts | `dashboardExtras` | Low |
| Add detail view actions | `detailExtras` | Low |
| Declarative action buttons | `actionButtons` | Very Low |
| Custom card layouts | `customCards` or `cardTemplate` | Low–Medium |
| New pages/tabs | Add to `TABS` array | Low |
| Workflow triggers | `WORKFLOW_MAP` + `WorkflowTriggerButton` | Low |
| Full page replacement | Skip `AppShell`, build your own | High |

**See `CLAUDE.md`** for the complete API reference with code examples.

### Modifying the data model

1. **Edit `schemas.py`** — add or modify schema definitions
2. **Re-run** `./run.sh` (or rebuild your Docker container)
3. **Refresh your browser** — new fields auto-render in forms and cards

Schema changes are non-destructive by default.

### Adding workflows

Define workflows in `setup.py` → `WORKFLOW_DEFINITIONS`. Re-run `./run.sh`
to push them. Trigger from the UI:

```javascript
// Programmatic
services.workflow.run('workflow-id', {{ field1: value1 }});

// Declarative (button in detail view)
var WORKFLOW_MAP = {{
  'order': {{
    workflowId: 'process-order',
    triggerLabel: 'Process Order',
    inputFields: ['order_number', 'customer_email']
  }}
}};
```

---

## Using AI Coding Assistants

This project ships with **`CLAUDE.md`** — a context file that teaches AI
assistants how to work with Supero apps correctly.

### Supported tools

| Tool | How it reads the context |
|------|--------------------------|
| **Claude Code** | Auto-detects `CLAUDE.md` in project root |
| **Cursor** | Reads `.cursorrules` (copy of `CLAUDE.md`) |
| **Windsurf** | Reads `.windsurfrules` (copy of `CLAUDE.md`) |
| **GitHub Copilot** | Paste `CLAUDE.md` into workspace instructions |
| **Generic LLM** | Paste `CLAUDE.md` contents into system prompt |

### Example prompts that work well

> "Add a KPI widget to the dashboard showing total revenue this month."

> "Create a detail view with a 'Send Email' button using the user's email field."

> "Add pagination to the main list view with 20 items per page and a search box."

> "Build a custom card layout with cover image, title, price, and status badge."

When starting a session, point the assistant at the context file:

```
Read CLAUDE.md first, then [your task].
```

This ensures the AI understands Supero conventions before writing code.

---

## Deploying to Production

Supero apps deploy to **any infrastructure you own** — there is no hosted
Supero runtime. You bring your own host.

### Path 1: Docker on a VPS / bare metal

```bash
# On your server
git clone <your-repo> {APP_SLUG}
cd {APP_SLUG}

# Create production .env (DO NOT commit this)
cat > .env <<EOF
SUPERO_DOMAIN={DOMAIN}
SUPERO_PROJECT={PROJECT}
SUPERO_API_KEY=ak_PROD_KEY_HERE
SUPERO_DEFAULT_TENANT={TENANT}
PORT={PORT}
EOF

# Start (runs in background, auto-restarts on reboot)
docker compose up -d
```

For production, **remove the volume mounts** from `docker-compose.yml` so
the image is self-contained.

### Path 2: Cloud platforms

Any platform that runs a Dockerfile works:

| Platform | Deploy command |
|----------|----------------|
| **Google Cloud Run** | `gcloud run deploy --source .` |
| **Fly.io** | `fly launch && fly deploy` |
| **Railway** | Connect repo, auto-detects Dockerfile |
| **Render** | Web Service → Docker runtime |
| **AWS App Runner** | Point at ECR image built from Dockerfile |
| **DigitalOcean App Platform** | Connect repo, select Dockerfile |
| **Heroku** | `heroku container:push web && heroku container:release web` |

For **all** of these: set your `.env` values as platform environment
variables (do **not** bake them into the image).

### Path 3: Static UI + serverless API proxy

Because `ui/` is pure static HTML/JS, you can split deployment:

- **Frontend** → Netlify, Vercel, Cloudflare Pages, S3+CloudFront
- **API proxy** → Cloud Run, Lambda, Cloudflare Workers

Update `ui/config.js` with your production API URL before deploying.

### Production checklist

- [ ] `.env` values set via platform env vars (NOT committed)
- [ ] `SUPERO_API_KEY` is a production key, rotated from dev
- [ ] Volume mounts removed from `docker-compose.yml`
- [ ] HTTPS enforced (via reverse proxy or platform default)
- [ ] Error monitoring enabled (Sentry, Rollbar, Datadog)
- [ ] Healthcheck endpoint responding on port {PORT}
- [ ] Container restart policy set (`restart: unless-stopped`)

---

## Troubleshooting

**"Domain not found" on login**
→ Check `SUPERO_DOMAIN` in `.env` matches your Supero dashboard.
  Re-run `./run.sh` to re-bootstrap.

**CORS errors in browser console**
→ You're hitting the API directly instead of through `server.py`.
  Load `http://localhost:{PORT}`, NOT `file://` on `index.html`.

**Schema changes don't show up**
→ Re-run your start command to push schema updates. Hard-refresh the
  browser (`Cmd+Shift+R` on Mac, `Ctrl+Shift+R` on Windows/Linux).

**`supero-ui.js` missing or outdated**
→ Delete `ui/supero-ui.js` and re-run — the CLI will fetch the latest.

**Bootstrap fails with "API key invalid"**
→ Check `SUPERO_API_KEY` in `.env`. Keys must start with `ak_`. Regenerate
  from the Supero dashboard if needed.

**Docker: "port {PORT} already in use"**
→ Stop the conflicting process or change the host port in
  `docker-compose.yml`: `ports: ["8080:{PORT}"]`.

**Docker: container exits immediately**
→ Check logs: `docker compose logs app`. Most common cause is missing
  or invalid `.env` file.

**Docker: changes to `ui/app.js` not reflecting**
→ Volume mounts should make changes instant. Hard-refresh browser.
  Check you haven't removed the volume mounts from `docker-compose.yml`.

**Login works but no data appears**
→ Check browser console. Common causes: RBAC policy missing
  (check `setup.py`), tenant mismatch, or schemas not bootstrapped.

**CRUD smoke tests failing**
→ Run with `--verbose` to see the exact HTTP errors. Use `--skip-tests`
  to launch anyway, but fix the failures before production.

**AI assistant broke `ui/app.js`**
→ Restore from git: `git checkout ui/app.js`. Always make the assistant
  read `CLAUDE.md` first.

**`.supero-run.log` has the full history**
→ Every `./run.sh` invocation is logged. Check this file first when
  debugging any issue.

---

## Learn More

- **Supero docs** — https://docs.supero.dev
- **Schema reference** — https://docs.supero.dev/schemas
- **Services catalog** — https://docs.supero.dev/services
- **Workflow engine** — https://docs.supero.dev/workflows
- **Community** — https://discord.gg/supero

---

## License

Your application code (`ui/app.js`, `schemas.py`, `setup.py`, and any
custom code you write) is yours.

The Supero platform, SDK, and `supero-ui.js` library are proprietary.
See https://supero.dev/terms for details.

---

<sub>Generated by Supero SDK `{SDK_VERSION}` on `{GENERATED_DATE}` · [supero.dev](https://supero.dev)</sub>
