docs/devvit-port-map.md

# Maryjane Genetics Devvit Architecture Map

Date: 2026-07-09

## Current Target

Maryjane Genetics is a Devvit Web game built around fictional plant genetics, shared leaderboards, clone exchange listings, and optional player-authorized agent control.

The app is now a Devvit Web project:

- `src/client`: React/Vite webview UI.
- `src/server`: Hono request handlers under `/api/*` and `/external/*`.
- `src/shared`: TypeScript simulation logic, state types, genetics, lab, deck, color, and market helpers.
- `public`: runtime pixel assets and generated sprite masks.
- `devvit.json`: webview entrypoints, server entrypoint, external endpoint declaration, subreddit menu, and install trigger.

Legacy Python and prototype files may remain in the local workspace for reference, but they are excluded from the Devvit publish source bundle and are not part of the runtime app.

## Devvit Constraints

- Client code calls the app server through same-origin `/api/*` endpoints.
- Devvit server handlers are request-scoped, not long-running services.
- Runtime persistence belongs in Reddit-managed Devvit storage, not cookies or local files.
- Large payloads should be capped and summarized before they reach the client or an agent client.
- Webview assets should be bundled or served from the app, not external CDNs.
- Any optional agent control must be player initiated, scoped, revocable, and provider-neutral.

## Runtime Surfaces

### Client Views

- Play: inventory, on-deck parents, growth, prediction, breeding, cloning, and live sprite rendering.
- Speciation Bench: germplasm, trait facets, prediction, and lineage exports.
- Deck: population summary, selected parents, recent crosses, receipts, and bus signals.
- Market: clone exchange listings, requests, offers, valuation hints, and leaderboard evidence.
- Observer Bus: local receipt and signal facade.
- FX: matrix-rain visual configuration.
- Agent Control: optional scoped handoff for any compatible player-authorized agent client.

### Server APIs

- Inventory: `/api/inventory`, `/api/inventory/starter`, `/api/inventory/clear`.
- Growth and breeding: `/api/seed/:seedId/grow`, `/api/breed`, `/api/clone`.
- Selection: `/api/selection` GET/POST.
- Lab: `/api/lab/germplasm`, `/api/lab/predict-cross`, `/api/lab/newick`.
- Deck and bus: `/api/deck/summary`, `/api/deck/signals`, `/api/bus/*`.
- Market: `/api/market/listings`, `/api/market/offers`, `/api/market/requests`.
- Leaderboard and passport data: `/api/leaderboard`, `/api/passport/:seedId`.
- Agent Control: `/api/agent-link/status`, `/api/agent-link/session`, `/api/agent-link/events`, `/api/agent-link/call`.
- Optional external compatibility bridge: `/external/mcp` for clients that understand JSON-RPC/MCP.

## Agent Control Contract

Agent Control is a neutral bridge, not a built-in model provider.

Player flow:

1. Player opens Agent Control.
2. Player creates or rotates a scoped session.
3. The app copies a paste-ready handoff packet.
4. The player gives that packet to any compatible agent or automation client.
5. The agent starts with `agent_bootstrap`, inspects state, reports status, then acts only within granted scopes.
6. The player can revoke the session from the UI.

Primary transport:

```json
{
  "method": "POST",
  "url": "<internalApi>",
  "headers": {
    "Authorization": "Bearer <Reddit WebView token>",
    "X-Agent-Link-Token": "<scoped session token>",
    "Content-Type": "application/json"
  },
  "body": {
    "tool": "<tool_name>",
    "args": {}
  }
}
```

First calls:

- `agent_bootstrap`
- `inspect_inventory`
- `inspect_requests`
- `inspect_market`
- `inspect_leaderboard`
- `inspect_bus`

Rules:

- No embedded LLM provider is required or assumed.
- No vendor-specific wording should appear in the player-facing handoff.
- Sessions are scoped by capability: `observe`, `garden`, `breed`, and `market`.
- Mutating tools should be used only after inspection and prediction where applicable.
- Agent events are shown in the UI feed and mirrored through the reactive UI intent system.
- External MCP is optional compatibility, not the default human-facing path.

## Observer Bus Facade

The Devvit Observer Bus is metadata-only and backed by app storage:

- `/api/bus/status`
- `/api/bus/signals`
- `/api/bus/receipts`
- `/api/bus/facilities`

Receipts and signals describe game events, market actions, and agent activity. They must not contain provider secrets, raw private transcripts, or external account credentials.

## Marketplace Model

The clone exchange is fictional in-game barter:

- Clone listings spend one source attempt and escrow the clone lot.
- Plant listings escrow the actual plant and should command a premium.
- Requests express demand for target traits, colors, rarity, or leaderboard-backed proof.
- Offers, counteroffers, refutes, and accepts are game-state operations only.
- There is no real currency, no cash-out path, and no real-world product exchange.

## Publish Notes

The publish source bundle should stay clean and Devvit-focused. `.gitignore` excludes:

- `node_modules/`
- `dist/`
- legacy prototype Python files
- old static prototype surfaces
- local-only generated or archived files

Validation before upload:

```bash
npm run type-check
npm run lint
npm run build
```

Public launch requires Reddit review because the app creates custom posts.

## Current Verification

- TypeScript build passes.
- Vite build passes.
- Lint passes with warnings only.
- Devvit version `0.0.18` was submitted for Reddit review on 2026-07-09.