PRODUCT SPEC — Overview (cross-platform umbrella)
PRODUCT SPEC — Overview (cross-platform umbrella)
Section titled “PRODUCT SPEC — Overview (cross-platform umbrella)”Umbrella spec for the OPEN PANEL product across all surfaces. Subordinate to
CANON.md(single source of truth). Per-surface detail lives inSPEC_WEB.md,SPEC_MOBILE.md,SPEC_DESKTOP.md,SPEC_BACKEND.md. Conforms to canon §3 (product), §4 (stack), §6 (contracts). Status: DRAFT v0.1. Brand/product nouns ALL-UPPERCASE in prose per style guide.
1. Product vision & the free reading experience
Section titled “1. Product vision & the free reading experience”The story is free; the universe is the asset. OPEN PANEL is a free comics platform. Every STANDARD ISSUE — a finished comic — is given away at no cost, forever, as the FOUNDATION’s charitable program. Reading is never gated, never paywalled, never ad-tracked. Money is made one layer up, by VARIANT, on premium VARIANT EDITIONS and licensing — never by charging for the core read.
The product is one reader engine on four surfaces: a single TS reading engine
(@openpanel/reader) renders identically on WEB, MOBILE, and DESKTOP, fed by the same
CPF artifact and the same BACKEND. One identity spans every surface and every context
(reader vs. collector/buyer/licensee). The promise to the reader is “library energy, not
paywall energy”: open the app, find a comic, read it now — online or offline, in your
language, accessibly.
2. Personas
Section titled “2. Personas”| Persona | Goal | Primary surface(s) | Context |
|---|---|---|---|
| Reader | Discover & read free comics, resume across devices, read offline | Mobile (daily), Web (reach), Desktop (library) | reader |
| Creator | Submit work, sign a machine-readable agreement, see royalties | Desktop (tooling host), Web | creator |
| Collector / Buyer | Buy premium VARIANT EDITIONS, own the universe | Web store, Desktop library | collector/buyer |
| Licensee / Partner | Browse available rights, license IP (merch, adaptation) | Web (VARIANT portal) | licensee |
| FOUNDATION staff | Editorial, ratings, moderation, COPPA/UBIT compliance | Web (internal) | operator |
| VARIANT staff | Manage store, partnerships, the Rights & Royalty LEDGER | Web (internal) | operator |
One account, many contexts: the same identity is a Reader and may also be a Buyer; staff roles are entitlements/permissions on that identity, never separate logins (canon §4, §6.3).
3. Core user journeys
Section titled “3. Core user journeys”Reader (the spine): discover (SSR catalog, search, recommendations) → open → read (page view or guided view) → progress auto-saved → resume on any surface → download for offline → optionally buy a VARIANT EDITION of a comic they love (entitlement granted, premium content unlocked). Free access is granted at every step without friction; the only checkout in the path is the optional VARIANT purchase.
Creator: apply → submit work (pages + panel metadata → CPF) → editorial review & content rating → sign the machine-readable Creator Agreement (canon §5, §6.5) → publish as a STANDARD ISSUE → watch downstream royalty share accrue in the LEDGER dashboard.
Licensee / Partner: browse the rights catalog in the VARIANT portal → request a grant (merch / adaptation / partnership) → arm’s-length terms recorded in the LEDGER → license executed → royalties flow up to the FOUNDATION (canon §2 royalty flow).
4. The shared reader engine (@openpanel/reader)
Section titled “4. The shared reader engine (@openpanel/reader)”A platform-agnostic TypeScript package, the single engine behind every client (canon §4). It consumes one input — the CPF artifact (canon §6.1) — and exposes reading as a headless core plus thin per-platform render bindings.
- Page view — full-page reading, spread-aware, fit-to-width/height.
- Guided view — panel-by-panel pan/zoom along the authored reading path (CPF panel regions + order). The defining premium-feel feature; works the same everywhere.
- Resumable progress — position model (issue + page + panel + offset) synced via the Content API (canon §6.2); resume mid-panel across surfaces.
- Offline — CPF packages cached locally; full read with zero network; progress queued and reconciled on reconnect.
- Accessibility — per-panel alt-text (from CPF), dyslexia-friendly mode (font, spacing, contrast), keyboard/switch navigation, screen-reader panel narration.
- Localization — CPF carries per-locale text/asset variants; engine selects by reader locale; right-to-left layout supported.
Rendering performance (tiled images, decode scheduling, prefetch of next panels) lives in the engine so all clients inherit it. Clients supply only input/gesture + storage adapters.
5. Feature matrix (feature × platform)
Section titled “5. Feature matrix (feature × platform)”| Feature | Web | Mobile | Desktop | Rationale |
|---|---|---|---|---|
| Catalog & discovery (SSR) | Full | Full | Full | SSR on Web for SEO/reach (canon §4) |
| Page view | ✓ | ✓ | ✓ | Core engine, all surfaces |
| Guided view (pan/zoom) | ✓ | ✓ (touch-native) | ✓ | Touch gestures shine on Mobile |
| Resumable progress (cross-device) | ✓ | ✓ | ✓ | One identity, synced position |
| Offline downloads | Limited (PWA cache) | Primary | Full library | Mobile = daily offline read; Desktop = collector’s library |
| Accessibility (alt-text, dyslexia) | ✓ | ✓ | ✓ | WCAG target everywhere |
| Localization / RTL | ✓ | ✓ | ✓ | Engine-level |
| VARIANT store / purchase | Primary | View + buy | Buy + own | Web is the commerce surface (canon §3) |
| Donations (FOUNDATION) | Primary | Link-out | Link-out | Stripe, separate account (canon §4) |
| Creator tooling (submit/CPF) | Partial | — | Primary | Desktop hosts creator tooling (canon §3) |
| VARIANT licensing portal | Primary | — | — | Partner/licensee workflow is desktop-class web |
| Signed installer / auto-update | — | App stores | ✓ (Tauri) | Desktop distribution model |
| Push / new-issue notifications | Web push | Native | Optional | Mobile is the daily-engagement surface |
Platform-specific choices are deliberate: Web carries reach + commerce + portals; Mobile carries daily offline reading + notifications; Desktop carries the deep offline library + creator tooling. The reader experience itself is identical on all three.
6. Cross-cutting requirements
Section titled “6. Cross-cutting requirements”- Accessibility: target WCAG 2.2 AA across all surfaces. Per-panel alt-text is a CPF-required field; dyslexia mode, full keyboard nav, and screen-reader panel narration are first-class, not add-ons.
- i18n / l10n: UI and content localized; CPF carries per-locale variants; RTL layouts supported. Reader locale drives engine selection.
- Performance budgets: catalog SSR LCP ≤ 2.5s on mid-tier mobile; first panel painted ≤ 1s from cached CPF; guided-view panel transition ≤ 100ms; offline read 0 network.
- Offline strategy: CPF packages are the offline unit. Mobile/Desktop persist full packages; Web PWA caches recently read. Progress writes queue locally and reconcile on reconnect (last-write-wins per position model).
- Privacy / COPPA: comics skew young (canon §6.7, §7.7). No third-party ad trackers. COPPA-aware: no behavioral profiling of minors, age-gating where required, parental controls, data minimization by default. GDPR posture maintained.
- Analytics: privacy-respecting event pipeline per the canon §6.7 event/analytics
contract — first-party only. Core events:
issue_opened,page_viewed,panel_viewed,read_completed,download_started/completed,resume_used,variant_purchased,donation_made. Events feed mission metrics + royalty attribution; never sold, never ad-targeted. - Entitlements: free access is always granted for STANDARD ISSUES — no entitlement check blocks a free read (canon §6.3). Premium VARIANT EDITIONS require an entitlement (entitlement check, not hard DRM — canon §4 DRM stance). One identity carries entitlements across surfaces.
7. Information architecture / navigation model
Section titled “7. Information architecture / navigation model”Shared mental model across all surfaces, so a Reader who learns one learns all:
- Read — Home/Discover, Series, Issue, Reader (the engine). The default landing.
- Library — Downloaded + in-progress + owned VARIANT EDITIONS. Per-identity.
- Store (VARIANT) — Premium editions, collectibles. Web-primary, browsable everywhere.
- Account — Identity, entitlements, locale, accessibility prefs, parental controls.
- Create (Creators) — Submissions, agreements, royalty dashboard. Desktop/Web.
- Portal (Licensees / staff) — Rights catalog, LEDGER, admin. Web only.
Context (reader vs. buyer vs. creator vs. licensee) reshapes which top-level areas are visible, but the navigation grammar and the reader are constant. The visual motif is the panel grid + gutter (canon §1.4).
8. Non-functional requirements & success metrics
Section titled “8. Non-functional requirements & success metrics”NFRs: free-at-scale (CDN-first asset delivery via R2/CDN, canon §4); availability ≥ 99.9% for catalog + reader; assets immutable & cacheable; minimal/no DRM on free comics; secure entitlement checks for premium; auditable LEDGER (canon §6.4); COPPA/UBIT compliance gates shipping (canon §7.10).
Success metrics (mission + business):
- Mission: monthly free reads, unique readers, completion rate, offline reads, # of localized titles, # of accessibility-mode sessions, creators paid.
- Reach: catalog SEO impressions, organic new readers, cross-surface resume rate.
- Business (VARIANT): VARIANT EDITION conversion from free readers, licensing grants executed, royalties flowed up to the FOUNDATION, donations.
- Trust: zero ad-tracker incidents, COPPA compliance, creator-payout timeliness.
9. Out of scope / future
Section titled “9. Out of scope / future”- Out of scope (v1): native ad network (never — mission conflict); hard DRM; social feed / UGC comics; in-app creator-to-reader messaging; AI-generated comics.
- Future: dedicated search index beyond Postgres FTS (canon §4); community/collections & reader curation; print-on-demand of VARIANT EDITIONS; animation/motion-comic guided view; partner white-label reader; expanded territories/jurisdictions (canon §2 assumes US).