moloapp/example/README.md

# Living example

Big living example project proving every MoloApp feature end to end.
Plan: `plans/10-workflow-example.md`, section 6.4.

Run it:

```sh
make -f example/example.mk example
./build/example/living-server 8080
```

Open `http://127.0.0.1:8080/` and click through the matrix. Narrow the
window to 360px: the top nav collapses into a dropdown menu.

Run the suite (37 route-level integration tests, real stack, no mocks):

```sh
make -f example/example.mk example-test
```

## Framework status

The framework is skeletal: `example/fw/` holds a compiling skeleton of the
public API (request, response hierarchy, router, application, views,
validation, forms, negotiation, templates, middleware, DI-shaped services,
errors, cookies, static, TLS stub, KV, cache, pubsub, events, metrics,
telemetry, sessions, auth, ORM stub, uploads, WebDAV, supervisor, tasks,
replication, REST client, OpenAPI, AI harness sample, release pipeline,
test client, loopback server). Gaps are marked in `example/SPEC.md` and in
each header. As siblings 01 through 09 land, this app re-binds to the real
namespaces route by route; the URLs, tests, and matrix stay stable.

## Coverage matrix

Feature -> route -> test file -> plan link. One row per feature; CI fails
on a missing row.

| Feature | Route | Test file | Plan |
|---|---|---|---|
| index | `/` | `tests/example/index_test.cpp` | `plans/10-workflow-example.md` 6.4 |
| health probe | `/health` | `tests/example/health_test.cpp` | `plans/09-cli-ops.md` health |
| routing | `/routing/hello/{name}` | `tests/example/routing/hello_test.cpp` | `plans/05-request-routing.md` |
| class views | `/routing/views/greet` | `tests/example/routing/views_test.cpp` | `plans/05-request-routing.md` |
| routers | `/routing/routers/nested/deep` | `tests/example/routing/routers_test.cpp` | `plans/05-request-routing.md` |
| app chaining | `/app1/app1/app1/whoami` | `tests/example/chain/deep_test.cpp` | `plans/05-request-routing.md` |
| orm sqlite | `/orm/users?backend=sqlite` | `tests/example/orm/users_test.cpp` | `plans/04-data.md` |
| orm postgres | `/orm/users?backend=postgres` | `tests/example/orm/users_test.cpp` | `plans/04-data.md` |
| basic auth | `/auth/me` | `tests/example/auth/me_test.cpp` | `plans/03-security.md` |
| login | `/auth/login` | `tests/example/auth/login_test.cpp` | `plans/03-security.md` |
| sessions | `/sessions/counter` | `tests/example/sessions/counter_test.cpp` | `plans/03-security.md` |
| uploads | `/uploads/file` | `tests/example/uploads/file_test.cpp` | `plans/03-security.md` |
| forms | `/forms/contact` | `tests/example/forms/contact_test.cpp` | `plans/05-request-routing.md` |
| validation | `/validate/user` | `tests/example/validate/user_test.cpp` | `plans/05-request-routing.md` |
| templates | `/templates/page` | `tests/example/templates/page_test.cpp` | `plans/05-request-routing.md` |
| formats | `/formats/data` | `tests/example/formats/data_test.cpp` | `plans/05-request-routing.md` |
| static disk | `/static/{name}` | `tests/example/static/files_test.cpp` | `plans/01-runtime.md` |
| embedded | `/embedded/{name}` | `tests/example/embedded/assets_test.cpp` | `plans/09-cli-ops.md` |
| streaming | `/streaming/feed` | `tests/example/streaming/feed_test.cpp` | `plans/06-realtime.md` |
| passthrough | `/streaming/passthrough` | `tests/example/streaming/passthrough_test.cpp` | `plans/06-realtime.md` |
| websocket | `/ws/chat` | `tests/example/ws/chat_test.cpp` | `plans/06-realtime.md` |
| socket.io | `/socketio/rooms` | `tests/example/socketio/rooms_test.cpp` | `plans/06-realtime.md` |
| sse | `/sse/events` | `tests/example/sse/events_test.cpp` | `plans/06-realtime.md` |
| webdav | `/webdav/files/` | `tests/example/webdav/files_test.cpp` | `plans/06-realtime.md` |
| pubsub | `/pubsub/publish` | `tests/example/pubsub/publish_test.cpp` | `plans/04-data.md` |
| events | `/events/fire` | `tests/example/events/fire_test.cpp` | `plans/02-observability.md` |
| metrics | `/metrics/counters` | `tests/example/metrics/counters_test.cpp` | `plans/02-observability.md` |
| telemetry | `/telemetry/trace` | `tests/example/telemetry/trace_test.cpp` | `plans/02-observability.md` |
| kv store | `/kv/items` | `tests/example/kv/items_test.cpp` | `plans/04-data.md` |
| cache | `/cache/lookup` | `tests/example/cache/lookup_test.cpp` | `plans/04-data.md` |
| tasks | `/supervisor/tasks` | `tests/example/supervisor/tasks_test.cpp` | `plans/07-supervisor-replication.md` |
| workers | `/supervisor/workers` | `tests/example/supervisor/workers_test.cpp` | `plans/07-supervisor-replication.md` |
| replication | `/replication/state` | `tests/example/replication/state_test.cpp` | `plans/07-supervisor-replication.md` |
| rest client | `/restclient/self` | `tests/example/restclient/self_test.cpp` | `plans/08-clients-openapi.md` |
| openapi | `/openapi.json` | `tests/example/openapi/docs_test.cpp` | `plans/08-clients-openapi.md` |
| docs page | `/docs` | `tests/example/openapi/docs_test.cpp` | `plans/08-clients-openapi.md` |
| ai harness | `/cli/ai` | `tests/example/cli/ai_test.cpp` | `plans/09-cli-ops.md` |
| workflow | `/workflow/release` | `tests/example/workflow/release_test.cpp` | `plans/10-workflow-example.md` 6.2 |
| redirects | `/redirect/here` | `tests/example/redirect/here_test.cpp` | `plans/05-request-routing.md` |

## Layout

```text
example/
  example.mk     # per-part make include (build, test, clean)
  SPEC.md        # mini-spec: behaviors, caps, formats, errors, gaps
  README.md      # this file
  main.cpp       # loopback server entry
  fw/            # skeletal framework public API (namespace molo::example::fw)
  app/           # demo routes (namespace molo::example::app)
  static/        # disk static assets (responsive CSS, tiny JS)
tests/example/   # route-level integration tests mirroring URLs
```