Overview
Plyrum Documentation Map
Last reviewed: 2026-05-13.
This directory is the product documentation source of truth. It separates what is already implemented from what is still required before a paid production launch.
Reviewed Code Areas
- Web app routes:
web/app/**/page.tsx - Web API routes:
web/app/api/**/route.ts - Billing and pricing:
web/lib/billing.ts,web/lib/pricing.ts,web/lib/fx.ts,web/lib/billing-cache.ts - Dashboard data:
web/lib/dashboard-data.ts - Model catalog and routing:
web/lib/provider-catalog.ts,web/lib/scoring.ts,web/lib/moa.ts - Prisma schema:
web/prisma/schema.prisma - Local and CI gates:
Makefile,scripts/smoke.sh,.github/workflows/* - CLI and engine docs context:
README.md,docs/architecture.md,docs/cost-arbitrage.md
Documentation Set
| Document | Purpose | Status |
|---|---|---|
docs/product-site.md | Website pages, user flows, dashboard behavior, launch gaps | Added |
docs/billing-and-payments.md | Current billing implementation, missing real payments, recommended payment methods, ledger design | Added |
docs/api-and-operations.md | API reference, env vars, smoke gates, local/prod runbook | Added |
docs/architecture.md | Existing architecture summary | Existing |
docs/cost-arbitrage.md | Existing MoA/direct cost evidence | Existing |
docs/product-gap-audit.md | Current implemented/partial/missing map against goal.md and donor scans | Added |
docs/F5_DONE.md | Existing v0.1/v0.2 readiness checklist | Existing |
Current Product Status
| Area | Status | Notes |
|---|---|---|
| Marketing site | Partial | / exists and shows model catalog. The public docs page is still a placeholder. |
| Auth | Implemented | Register/login/refresh with JWT and DB refresh-token rotation. |
| Dashboard | Implemented MVP | Dashboard, model settings, reliability, doctor, usage, transcripts, MoA, audit pages exist. |
| CLI | Implemented MVP | Auth, TUI, model selection, run, usage, audit, doctor, permissions, workflow, memory/persona commands. |
| Model orchestration | Implemented | Scoring, compliance filters, reliability, MoA, Self-MoA, route explanations, progress events. |
| Usage accounting | Implemented | UsageEvent rows are persisted with canonical usage and micro-RUB cost. |
| Wallet balance display | Partial | CreditWallet exists and /api/balance reads spendable balance as total minus reserved. |
| Wallet usage debit | Implemented/partial | Completed positive-cost usage creates idempotent WalletLedgerEntry(type=usage_debit) rows and updates wallet balance transactionally. Hard preflight rejection and balance hold/reservation exist behind PLYRUM_BILLING_ENFORCE_BALANCE=1; real top-up is still missing. |
| Real top-up/payment provider | Partial/contract-only | /billing/topup is now a sandbox-oriented checkout form with payment history and return-state display. Payment, PaymentWebhookEvent, FiscalReceipt, and Invoice DB tables exist. Mock checkout/history/webhook APIs exist, sandbox succeeded webhooks can idempotently credit wallet, admin-only sandbox refunds can idempotently debit wallet, YooKassa hosted checkout/webhook code can credit wallet after provider re-fetch verification, admin YooKassa refunds call provider /v3/refunds before local ledger debit, accepted top-ups/refunds create pending FiscalReceipt rows, and YooKassa checkout requires explicit terms acceptance. Checkout links to /legal/offer, /legal/privacy, /legal/refund, and /legal/tariffs. Paid launch is still blocked by YooKassa sandbox browser E2E, external fiscal/refund receipt submission, final legal review/entity details, production payment methods and provider-specific reconciliation/runbook. |
| Browser E2E | Partial | Playwright config and route tests exist. Payment browser E2E cannot fully exist until top-up UI and real checkout/webhook exist. |
| Production legal docs | Partial/draft | Customer-facing draft pages exist at /legal/offer, /legal/privacy, /legal/refund, and /legal/tariffs, and checkout links to them. They still need legal review, seller details, fiscal receipt policy and final public contacts before real payments. |
Documentation Required Before Paid Launch
User-facing:
- Product overview: what Plyrum does, which tasks it is good for, and where it should not be trusted blindly.
- CLI guide: install, login, run, TUI controls, commands, sandbox permissions, file-write behavior, audit and memory controls.
- Web dashboard guide: account, model settings, doctor, reliability, usage, transcripts, why/explanations, audit.
- Model policy: supported providers, model IDs, routing modes, compliance filters, data residency, privacy tiers.
- Pricing and tariffs: how token usage becomes RUB cost, what is included, how prepaid balance works, minimum top-up, refunds, taxes.
- Payment instructions: cards/MIR, SBP, SberPay/T-Pay where supported, business invoice flow.
- Terms of service / public offer.
- Privacy policy, including 152-FZ personal data handling.
- Refund policy.
- Data retention and deletion policy.
- Security page: secret handling, provider-key storage, audit log, sandbox limitations, incident contact.
Internal/operator:
- Production runbook: deploy, migrate, rollback, backup, smoke, restore.
- Billing ledger runbook: top-up, debit, refund, adjustment, reconciliation.
- Payment-provider integration notes: checkout, webhook verification, idempotency, fiscal receipts, sandbox/live modes.
- Incident response: provider outage, double-charge, webhook replay, data leak, model producing unsafe output.
- Compliance matrix: who can enable providers/models, org policy inheritance, no-PII mode, residency enforcement.
- Release checklist: tests, smoke, trust guard, secret scan, browser E2E, live payment sandbox proof.
Next Documentation Work
- Turn
/docsin the web app from a placeholder into a real product docs landing page that links to public docs. - Add an OpenAPI spec once the payment endpoints are implemented.
- Add screenshots/GIFs for CLI TUI and dashboard flows.
- Add a customer-facing pricing page after the tariff and payment-provider decisions are locked.
- Add a legal-review pass for offer/privacy/refund texts before accepting real money.