File size: 5,530 Bytes
1a343cd | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 | # 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.
|