the-fountainai.git · README.md

revision f3c153cb7e5a42f63ab04dc521516a78cceec74b · complete file
# FountainAI Playbill

See [OPENAPI_COVERAGE.md](OPENAPI_COVERAGE.md) for a catalog of services, specs, and tools lacking OpenAPI coverage.

Imagine FountainAI as a bustling theatre. Every user request is a script handed to the stage door, where the `gateway` decides whether the show can begin. The [Gateway API](openapi/v1/gateway.yml) and its [Swift stage crew](services/GatewayServer/GatewayApp) set the scene.

The first actor to read the script is the [Auth Gateway](openapi/personas/auth.md), following the cues in [its contract](openapi/v1/auth-gateway.yml) and the lines in [AuthGatewayPlugin+GatewayPlugin.swift](services/GatewayServer/GatewayApp/AuthGatewayPlugin+GatewayPlugin.swift). If the ticket is valid, the curtain lifts for the next gatekeeper, the [Rate Limiter](openapi/personas/rate-limiter.md), who keeps count using [rate-limiter-gateway.yml](openapi/v1/rate-limiter-gateway.yml) and [RateLimiterGatewayPlugin+GatewayPlugin.swift](services/GatewayServer/GatewayApp/RateLimiterGatewayPlugin+GatewayPlugin.swift).

Budget is checked by the [Budget Breaker](openapi/personas/budget-breaker.md) per [budget-breaker-gateway.yml](openapi/v1/budget-breaker-gateway.yml) and [BudgetBreakerGatewayPlugin+GatewayPlugin.swift](services/GatewayServer/GatewayApp/BudgetBreakerGatewayPlugin+GatewayPlugin.swift). The script itself is inspected by the [Payload Inspector](openapi/personas/payload-inspection.md) with [payload-inspection-gateway.yml](openapi/v1/payload-inspection-gateway.yml) guiding [PayloadInspectionGatewayPlugin+GatewayPlugin.swift](services/GatewayServer/GatewayApp/PayloadInspectionGatewayPlugin+GatewayPlugin.swift). For dangerous plot twists, the [Destructive Guardian](openapi/personas/destructive-guardian.md) consults [destructive-guardian-gateway.yml](openapi/v1/destructive-guardian-gateway.yml) and [DestructiveGuardianGatewayPlugin+GatewayPlugin.swift](services/GatewayServer/GatewayApp/DestructiveGuardianGatewayPlugin+GatewayPlugin.swift), while the [Security Sentinel](openapi/personas/security-sentinel.md) reviews everything against [security-sentinel-gateway.yml](openapi/v1/security-sentinel-gateway.yml) and [SecuritySentinelGatewayPlugin+GatewayPlugin.swift](services/GatewayServer/GatewayApp/SecuritySentinelGatewayPlugin+GatewayPlugin.swift).

Behind the scenes, the [Role Health Checker](openapi/personas/role-health-check.md) keeps the ensemble in shape through [role-health-check-gateway.yml](openapi/v1/role-health-check-gateway.yml) and [RoleHealthCheckGatewayPlugin+GatewayPlugin.swift](services/GatewayServer/GatewayApp/RoleHealthCheckGatewayPlugin+GatewayPlugin.swift). Once the gates are cleared, the [LLM Gateway](openapi/v2/llm-gateway.yml) invites the language model via [LLMGatewayPlugin+GatewayPlugin.swift](services/GatewayServer/GatewayApp/LLMGatewayPlugin+GatewayPlugin.swift). Chain-of-thought logging has been removed from the gateway.

Props and past performances are stored in FountainStore by the [Persistence Service](openapi/personas/persist.md) described in [persist.yml](openapi/v1/persist.yml) and performed in [services/PersistServer](services/PersistServer).

Even the supporting cast has roles: the Bootstrap service seeds characters like [Drift](openapi/personas/drift.md) and [Semantic Arc](openapi/personas/semantic-arc.md) using [bootstrap.yml](openapi/v1/bootstrap.yml) so every play starts with the right troupe.

When the curtain falls, the response is handed back to the audience as the final line, completing the journey from script to stage and back again. FountainAI’s theatre turns technical requests into performances, with each persona playing its part, guided by OpenAPI scripts and Swift code that keep the show running smoothly.

## macOS Apps

A macOS GUI is not currently included. If/when we add one, we will document build and packaging here.

### Launcher CLI wrapper (Phase 1)

Use the helper to start/stop the FountainAiLauncher and check status/logs without Xcode:

- Start: `bash Scripts/launcher start` (waits for control plane)
- Stop: `bash Scripts/launcher stop`
- Status: `bash Scripts/launcher status`
- Logs: `bash Scripts/launcher logs [-f]`

Notes:
- The wrapper sets `FOUNTAINAI_ROOT` to the repository root automatically.
- First start builds the launcher (release). It may take a few minutes on initial run.
- Control plane URL: `http://127.0.0.1:9090/status`.

Create new GUI apps with the same pattern:

- Scaffold: `Scripts/new-gui-app.sh <AppName>`
- Build/Bundle/Launch: `swift build --product <AppName> && bash Scripts/make_app.sh <AppName> && open dist/<AppName>.app`

More details:
- GUI Quickstart & Scaffolding: `docs/GUI_App_Quickstart_and_Scaffolding.md`
- Q&A: `docs/Q&A/GUI_App_Scaffolding_QA.md`