# www.mmoframework.fr — build plan
The new public site of MMOFramework: the pitch (built for AI), a playground, one page per library with its
demo, and the whole documentation. It replaces the current www.mmoframework.fr (today the mmo.client demo).
Mockup: https://claude.ai/artifact/W1TsRfbZpxVxhpogRn1v9R (Blueprint direction, FR and EN boards).
## Decisions taken
| | |
|---|---|
| Structure | homepage = AI pitch · `/playground` = scaffold a project · `/libraries` = the hub · `/documentation` |
| Runtime | a real MMO application: mmo.core + mmo.client, deployed by mmo.admin. The site is its own proof |
| Existing site | replaced. The current mmo.client page becomes `libraries/mmo.client` (its demo tab) |
| Languages | French and English, switchable on every page |
| Audience | developers and clients of Hydra Agency; the framework is presented as the agency's stack |
| Brand | fresh: Blueprint (navy ground, 40 px grid, teal accent, IBM Plex Sans + Mono, "FIG. 0n" section labels) |
| AI proof | MCP + agent docs, a recorded agent session, measured numbers |
| Docs code | moved into mmo.doc first, as a read-only helper both this site and `../mcp` call |
| Playground | first version as below: generation and browsing real, deployment replayed, nothing executed |
| URLs | `/fr/…` and `/en/…`; `/` redirects by the browser's language |
| Benchmark | against both Laravel + Vue and Symfony + Twig |
| References | none named for now: the agency section has no client list |
| Contact | the form's messages go to marc@hydra-agency.com |
| Current site | it is mmo.client's demo: its content moves to `libraries/mmo.client` |
## Architecture
The site is a project of its own, scaffolded like any other:
```bash
php ~/dev/src/MMO/master/tools/mmo.php project ~/dev/src/mmoframework.fr/www \
--name=www.mmoframework --namespace=MMO\www --title=MMOFramework
```
Same shape as `../mcp`: `bootstrap.php`, `www/index.php`, `src/` (namespace `MMO\www`), `configs/`,
`deploy.json`, `libs` → `~/dev/src/MMO/master/libs`, `AGENTS.md`, `phpunit`.
| Dependency | Why |
|---|---|
| mmo.core, mmo.client | the application, the pages, the `.jhs` elements, the theme |
| mmo.doc | the documentation pages and the symbol search, served the way `../mcp` serves them |
| mmo.pdo (SQLite) | the demos' throwaway data, and the playground's sessions |
| mmo.math, mmo.pdf, mmo.editor… | only the libraries whose demo runs live on the site (see Demos) |
**The documentation.** Reuse `../mcp`'s approach as is: `connectDocumentation()` (mmo.doc's page tree, renderer
and search only, never `Documentor::Shared()`), `scripts/build-docs.php` run before the phars are built.
`connectDocumentation()` and `build-docs.php` move into mmo.doc first, as a read-only documentation helper, in a
separate change; `../mcp` then calls it instead of its own copy, and so does this site.
**The MCP server is this site's** (merged from `../mcp`): `POST mcp.json`, in every mode, documenting every library
it packages (`MCPController` with `discovered`, configs/config.json); its full-text search and its reader of skills
and the guide are `search` and `search/read` (`src/Documentation.php`, which asks the server in-process). Every link
names `https://www.mmoframework.fr/mcp.json` -- the framework's skills, mmo.client's demo, hydra-agency.com -- so
mcp.mmoframework.fr can be retired once this site is live (until then, those links answer nothing).
**Languages.** `MMO\core\I18n`, as mmo.client and mmo.admin already do: English source strings, `src/i18n/fr.php`
for French (`mmo.json`'s `i18n`). URLs carry the language (`/fr/…`, `/en/…`); `/` redirects by
`Accept-Language`, French when it names neither. The framework's documentation stays in English in both versions, with a
one-line note on the French pages.
**Theme.** `src/styles/app.scs` on top of mmo.client's design system: the Blueprint tokens (`$color.*`, the grid
background, the type scale) override the framework's, nothing re-implemented. IBM Plex is self-hosted in
`www/assets/fonts` (no Google Fonts call: no third-party request, nothing to consent to).
## Pages
| Route | Content | Built from |
|---|---|---|
| `/` | hero, agent replay, numbers, the four AI pieces, playground teaser, 15 library tiles, agency CTA | `src/pages/home` |
| `/ai` | how to connect an agent: the `claude mcp add` line, AGENTS.md, llms.txt, the skills, `verify` | `src/pages/ai` |
| `/playground` | configure → browse the files → deploy (below) | `src/pages/playground` + `` |
| `/libraries` | the hub: the libraries by group, each with its one line and its status | `mmo.json` of each library, read like the hub does |
| `/libraries/{lib}` | Overview · Demo · Documentation · API tabs | its `README.md`, its `docs/`, its demo element |
| `/documentation/…` | mmo.doc's index, every library's pages, the symbol search | mmo.doc |
| `/contact` | the agency, a contact form sending to marc@hydra-agency.com | mmo.core form + mail |
New `.jhs` elements, in `src/customElements/`:
- `` plays back a recorded agent session (a JSON transcript: who, what, when), step by step or
continuously;
- `` runs the three steps of the playground against its API;
- `` is the shared frame of a library demo: controls on one side, the PHP, its output and its
result on the other.
## Demos
The rule: **a visitor never runs code they wrote.** Every demo is a fixed piece of PHP with parameters the
visitor chooses (a role, a sort, a formula from a list or parsed by mmo.math, an XP curve's settings), served by a
small read-only JSON route per library. Per request, a time limit and a memory limit; the routes are rate-limited.
| Library | Demo | Live? |
|---|---|---|
| mmo.client | today's www.mmoframework.fr content: `.jhs` anatomy, the elements | yes, client side |
| mmo.pdo | filters and sorting → the PHP, the SQL PDOPrinter writes, the rows | yes, SQLite reset per session |
| mmo.math | type an expression → parsed tree, domain, value | yes |
| mmo.editor | the editor on a card of the page | yes, client side |
| mmo.pdf | fill a sample form → download the PDF | needs pdftk on the server: check IONOS |
| mmo.ocr | a sample image → blocks as SVG | needs Tesseract: pre-computed if not available |
| mmo.metrics | this site's own anonymous statistics | yes, once it runs on the site |
| mmo.admin | the deploy log of this very site (its real history) | yes, read-only |
| mmo.core, oauth, edms, mongodb, git, doc | code + recorded output | recorded |
## The playground
What the visitor does: name an app, pick libraries, get the generated project, browse its files, download it
as a zip, watch it be deployed.
**The constraint**: the site is deployed to the IONOS shared webspace like `../mcp` (no containers, no sudo).
The first version:
1. **Generation is real.** The site calls the same code as `tools/mmo.php project`: mmo.admin's
`ProjectScaffold`, its skeleton and its deployment files. A project is a function of its name and its
libraries, so it is made again for each request, in memory: no session folder, nothing to delete. The name and
namespace are validated with the same rules as the command. No `git init`, no `libs` link.
2. **Browsing is real.** The file tree and contents are the generated files, read-only; "Download" zips them.
3. **The deployment is a replay.** A recorded mmo.admin deploy, with the visitor's project name and libraries
in it, and a rollback button. Nothing is deployed anywhere.
4. **"Open the application"** shows the project's home page rendered by a pre-built instance of the template,
not the visitor's generated copy (nothing generated is ever executed).
Visitors running their own generated app is left for a second version, on a separate server with containers.
## The AI proof
- **The recorded session**: a real Claude Code session on a real feature (proposal: the invoices page with its
PDF export, as in the mockup), recorded as a JSON transcript of its tool calls, replayed by ``.
The full transcript is downloadable.
- **The numbers**: a protocol rather than an estimate. The same feature specification, built by the same
agent: on MMOFramework with the MCP server, on Laravel + Vue, and on Symfony + Twig. Measured: tokens, wall time, number of
turns, errors caught by the checks, whether the result passes its tests. Several runs each, the medians
published, the protocol and transcripts published with them.
## Deployment
`deploy.json` like `../mcp`'s: the IONOS webspace, folder `mmoframework.fr/www`, `www.mmoframework.fr` pointed at
its `web` link. Before switching the domain, the site runs on a test name (`next.mmoframework.fr`), and the
current site's content is moved into `libraries/mmo.client`.
## Done along the way
- **Contact** (`src/pages/contact`, `ContactController`): the form mails marc@hydra-agency.com from
noreply@mmoframework.fr, as plain text answering its writer; a hidden field drops robots, a visitor sends 5 an
hour. A checkout mails no one: `configs/dev.json` gives it an outbox folder. For the launch: noreply@mmoframework.fr
must exist on the server that sends it.
## Phases
0. **mmo.doc** (done, mmo.doc 3.1.0): move the read-only documentation helper and `build-docs.php` out of `../mcp` into mmo.doc;
`../mcp` calls it, its tests still pass.
1. **Foundation**: scaffold the project, the Blueprint theme, the layout (header, footer, language switch),
i18n, deploy to `next.mmoframework.fr`. Done except the deployment (deploy.json has no server yet) and the
self-hosted fonts (IBM Plex still comes from Google Fonts: `configs/config.json`). The documentation is already
connected (`\MMO\doc\connectReadOnly()`), so phase 2 starts from a working `/documentation`.
2. **Docs and libraries** (done): the documentation (mmo.doc), the hub, the library pages with their Overview,
Documentation and API tabs (`src/Libraries.php`, `src/pages/libraries/`); a release packages every library
(scripts/bootstrap.php's `inc`) and builds their code reference (`scripts/build-docs.php`). Left: a release has
no README (the Overview shows the manifest only), and mmo.ocr and mmo.metrics are not packaged (as in mcp).
3. **Homepage and AI page** (done, with placeholders): the homepage's sections and the Why AI page
(`src/pages/home`, `src/pages/ai`, their texts in `src/content/`), the session replayed by ``
(`src/customElements/mmo-replay.jhs`). Left: the replayed session is an EXAMPLE written for the site, labelled so,
until a real recording replaces it; the numbers are `[X]` until the benchmark (phase 6).
4. **Demos**: mmo.client (the current site), mmo.pdo, mmo.math first; then the others. Done for
mmo.pdo and mmo.math: `DemoController` (`demo/{pdo,math}.json`, read-only, 422 on any parameter
the demo does not offer), `src/demos/Demos.php`, `` and `src/pages/libraries/demos/.phtml`
(the Demo tab opens first when a library has one). mmo.client's: the site's own `mmo-replay.jhs` beside the
element it compiles to, and shipped elements live in ``. The demo routes allow 60 requests a
minute per visitor (`src/RateLimit.php`, counts by a hash of the address, 429 with Retry-After). Left: the other
libraries' demos, and where mmo.client's full component browser (today's www.mmoframework.fr, its demo app)
lives once this site replaces it.
5. **Playground** (done): generation, browsing, zip, the deploy replay. The project is made by mmo.admin's
`ProjectScaffold` -- the very code of the hub's `mmo.php project`, moved into mmo.admin with the skeleton
(`libs/admin/project/`) and packaged in its phar -- again for each request from its name and libraries, so
nothing is stored and nothing generated is ever run (`src/playground/Playground.php`, `PlaygroundController`:
`playground/project.json` and `.zip`, 60 requests a minute per visitor).
6. **Proof**: the benchmark, the final recorded session, the numbers. The tooling is done: the protocol and the
feature's text (`docs/benchmark/PROTOCOL.md`, `SPEC.md`), how to run it (`RUNNING.md`), a transcript read into
steps and measures (`src/sessions/Transcript.php`: paths made relative, secrets masked, each request counted
once), `scripts/import-session.php` (the home page's replay) and `scripts/benchmark.php` (the runs, their
medians). The home page and the Why AI page switch to them by themselves. Left: the runs themselves -- they spend
real tokens, and Laravel and Symfony need `composer`, which this machine does not have.
7. **Launch**: content review FR/EN, performance, accessibility, switch www.mmoframework.fr.
## Still open
- Who runs the benchmark, and when (it needs the final feature specification and API budget for several runs
on three stacks).
- Whether the IONOS webspace has `pdftk` and Tesseract, for the mmo.pdf and mmo.ocr demos.