Relevant source files

The following files were used as context for generating this wiki page: - [docs/playground.html](https://github.com/miaadteam/lesan/blob/main/docs/playground.html) - [.travis.yml](https://github.com/miaadteam/lesan/blob/main/.travis.yml) - [LICENSE](https://github.com/miaadteam/lesan/blob/main/LICENSE) - [QWEN.md](https://github.com/miaadteam/lesan/blob/main/QWEN.md) [FILE_URLS] (use these URLs when citing sources in the content): - docs/playground.html: https://github.com/miaadteam/lesan/blob/main/docs/playground.html - .travis.yml: https://github.com/miaadteam/lesan/blob/main/.travis.yml - LICENSE: https://github.com/miaadteam/lesan/blob/main/LICENSE - QWEN.md: https://github.com/miaadteam/lesan/blob/main/QWEN.md

# Playground Guide ## Introduction The **Playground** is an interactive, web‑based environment bundled with the Lesan framework that lets developers experiment with actions, models, and queries without writing a full client application. It is exposed when the server is started with the `playground: true` flag (see the example in *QWEN.md*). The Playground page lives under the documentation site (`docs/playground.html`) and is part of the generated static site that Travis CI builds and publishes to GitHub Pages (*`.travis.yml`*). This guide explains how the Playground is wired into the Lesan server, how it is built and deployed, and how developers can use it to test their schemas and actions quickly. ## 1. Architecture Overview ### 1.1 High‑Level Components | Component | Role | Source | |-----------|------|--------| | **Lesan Server** (`coreApp.runServer`) | Starts an HTTP server, optionally enables the Playground UI | QWEN.md (example) | | **Playground UI** (`docs/playground.html`) | Static HTML/JS page that sends POST requests to `/lesan` endpoint | docs/playground.html | | **CI Build Pipeline** (`.travis.yml`) | Builds the documentation site (including Playground) and publishes it to GitHub Pages | .travis.yml | | **MongoDB** | Backend data store used by actions invoked from the Playground | QWEN.md (framework description) | ### 1.2 Data Flow The following flowchart visualises a typical request from the Playground UI to the Lesan server and back to the browser. ```mermaid graph TB userNode[User] -->|open#40;Playground UI#41;| playgroundNode[Playground UI] playgroundNode -->|POST #47;lesan#40;JSON payload#41;| serverNode[Lesan Server] serverNode -->|exec act #47; query| odmNode[ODM Layer] odmNode -->|read#47;write| dbNode[MongoDB] dbNode -->|result set| odmNode odmNode -->|response| serverNode serverNode -->|JSON response| playgroundNode playgroundNode -->|render result| userNode ``` *Explanation*: 1. The user opens the Playground page (served as a static file). 2. The UI sends a JSON payload to the `/lesan` endpoint of the running Lesan server. 3. The server routes the request to the appropriate **Act** function via the ODM layer. 4. The ODM interacts with MongoDB, then returns data back up the chain. 5. The Playground UI displays the formatted response. *Sources*: docs/playground.html, QWEN.md, .travis.yml ## 2. Enabling the Playground ### 2.1 Server Configuration When creating the core Lesan instance, the `runServer` method accepts an options object. Setting `playground: true` injects the Playground UI route. ```typescript coreApp.runServer({ port: 1366, playground: true }); ``` *Source*: QWEN.md (example code) ### 2.2 Build & Deployment The static Playground page is part of the documentation site. Travis CI builds the site with `npm run build` and exports it with `npm run export`. The exported `out` directory (or `website/out`) is then pushed to the `gh-pages` branch. ```yaml script: - cd website - npm install - npm run build - npm run export - touch out/.nojekyll deploy: provider: pages local_dir: website/out # ... (other deploy settings) ``` *Source*: .travis.yml ## 3. Using the Playground ### 3.1 Request Structure The Playground UI expects a POST body that matches Lesan’s RPC format: ```json { "service": "main", "model": "country", "act": "addCountry", "details": { "set": { "name": "Iran", "population": 85000000, "abb": "IR" }, "get": { "_id": 1, "name": 1, "population": 1, "abb": 1 } } } ``` *Source*: QWEN.md (API usage example) ### 3.2 Example Session 1. **Select Model & Action** – Choose `country` and `addCountry` from dropdowns. 2. **Provide `set` Data** – Fill the JSON editor with the `set` object. 3. **Define Projection (`get`)** – Optionally specify which fields to return. 4. **Execute** – Click **Run**; the UI sends the payload to `/lesan`. 5. **View Result** – The response JSON is displayed in the result pane. ### 3.3 Common Pitfalls | Issue | Symptom | Fix | |-------|----------|-----| | Missing `playground: true` flag | `/playground` returns 404 | Enable the flag in `runServer`. | | CORS errors when running locally | Browser blocks request | Serve Playground from same origin (use `npm run dev` or the built site). | | Invalid JSON payload | Server returns validation error | Use the schema validator shown in the UI (generated from `coreApp.schemas.selectStruct`). | *Source*: QWEN.md (mentions playground for testing) ## 4. Extending the Playground Developers can add custom UI components or pre‑filled examples by editing `docs/playground.html`. The page already includes the necessary scripts to discover the server’s base URL and to send requests. ### 4.1 Adding a New Example ```html

Add User Example

{
  "service":"main",
  "model":"user",
  "act":"addUser",
  "details":{ ... }
}

``` *Source*: docs/playground.html (structure of the page) ## 5. Security & Licensing The entire Lesan project, including the Playground, is released under the **GNU Affero General Public License v3** (AGPL‑3.0). This means any public deployment of the Playground must also provide source access to users of the service. *Source*: LICENSE ## Conclusion The Lesan Playground offers a lightweight, browser‑based sandbox for developers to interact with their models and actions in real time. By enabling the `playground` flag, the server automatically serves `docs/playground.html`, which communicates with the `/lesan` endpoint. The CI pipeline (`.travis.yml`) ensures the Playground page is built and published alongside the rest of the documentation. Understanding the architecture, request format, and deployment steps enables teams to leverage the Playground for rapid prototyping and debugging.