PRD 00: Legacy Blinkin Preservation Platform

Problem Statement

The old Blinkin platform is split across Picasso FE, Zweistein, and Studio API. Together they contain the real product: visual flow building, companions, Houston runtime, chat, agents, controls, billing, quotas, auth, media, forms, integrations, analytics, and deployment material.

The problem is not that the old product lacks features. The problem is that the features are scattered, outdated in parts, cloud-specific in places, and risky to operate as-is. We need a new project that preserves the complete old product behavior while making it understandable, testable, and deployable on Hetzner.

Solution

Build LegacyBlinkin-2-Hetzner as the new consolidated platform specification and future implementation target.

The platform must preserve the legacy feature set while improving:

• security boundaries;
• deployment clarity;
• tenant isolation;
• feature documentation;
• observability;
• backup and restore;
• maintainability;
• runtime safety for generated UI;
• cloud portability for Hetzner.

The project must not modify blinkin-2-platform. Legacy references are read-only.

Legacy Source Coverage

• picasso-fe-reference: visual flow editor, board/editor interactions, Houston runtime, widget embed, runtime component catalog.
• zweistein-reference: chat workspace, agent/product navigation, generated controls, billing, quotas, subscriptions, Python query engine, ingestion, AI tools.
• studio-api-reference: Auth0/JWT, tenants, tenant users, flow CRUD, flow protection, forms, submissions, integrations, media, webhooks, statistics, email templates.

Product Principles

• Preserve old behavior before redesigning.
• Keep every major legacy capability unless explicitly retired later.
• Replace unsafe implementation techniques with safer equivalents.
• Treat old repos as feature evidence, not architecture commandments.
• Write requirements in product language before implementation starts.
• Deploy to Hetzner with a real operational model: services, data, storage, logs, health checks, backups.

Primary Actors

1. Workspace owner: creates orgs, pays for plans, manages users, billing, and security.
2. Admin/operator: configures integrations, webhooks, spaces, agents, controls, and deployment settings.
3. Creator/designer: builds boards, companions, forms, runtime flows, and publishable experiences.
4. Agent builder: configures agents, tools, prompts, knowledge sources, and generated controls.
5. End user: uses public or private companions, submits forms, uploads media, chats, and completes flows.
6. External user: accesses protected companions through external auth, group membership, or shared links.
7. Developer/operator: deploys, monitors, backs up, restores, and maintains the Hetzner system.

User Stories

1. As a workspace owner, I want to preserve my old Blinkin product behavior, so that existing workflows do not disappear during the move.
2. As a creator, I want to build visual flows and companions, so that I can publish interactive user experiences.
3. As a creator, I want a board/editor surface, so that I can arrange steps, content, forms, AI nodes, and routing visually.
4. As an end user, I want the runtime to support forms, media capture, routing, and submissions, so that published companions work like the old platform.
5. As an admin, I want tenant and user management, so that teams can use the platform safely.
6. As an admin, I want integrations and webhooks, so that old workflows can connect to external tools.
7. As an agent builder, I want chat, tools, research, OCR, media analysis, and generated UI controls, so that AI workflows keep their old power.
8. As a workspace owner, I want billing, trials, plans, quotas, usage records, and wallet/credit tracking, so that the platform can run as a SaaS product.
9. As an operator, I want Hetzner deployment docs and health checks, so that the new platform can be hosted reliably.
10. As an operator, I want backups and restore steps, so that production data can survive server failure.
11. As a security owner, I want generated UI to run safely, so that legacy dynamic controls do not expose users to browser-side code execution risk.
12. As a product designer, I want the full old feature inventory written as PRDs, so that implementation can happen in small, understandable slices.

Core Product Areas

Identity and Tenancy

Preserve Auth0/JWT identity, tenant/org context, org membership, roles, invites, profile settings, external users, external groups, and public/companion auth.

Flows, Boards, and Companions

Preserve flow CRUD, board listing, companion listing, flow protection, folders, collections, tags, publishing, results, submissions, history, form definitions, node templates, and share/embedding settings.

Editor and Runtime

Preserve the Picasso-style visual editor, creation menus, React Flow canvas behavior, top bar, editor/results/share/settings sections, Houston runtime, embed widget, runtime component catalog, routing, media capture, whitelabeling, and analytics.

Chat, Agents, and Controls

Preserve conversations, message history, attachments, voice input, agents, bots, agent threads, tools, generated controls, dynamic UI configuration, message feedback, favorites, and AI assistant behavior.

AI, Search, and Ingestion

Preserve deep research, OCR, web search, video analysis, image generation, TTS, PDF filling, file ingestion, web ingestion, conversation ingestion, vector search, knowledge spaces, and query engine behavior.

Billing and Quotas

Preserve Stripe checkout, portal, upgrades, trials, subscription plans, quota definitions, usage counters, usage records, token pricing, wallet/credits, limit modals, and billing UI.

Integrations, Media, and Webhooks

Preserve integration management, credentials, media upload, image/video/audio processing, HEIC conversion, Mux/video handling where needed, form submissions, webhook delivery, email templates, and statistics.

Admin, Analytics, and Operations

Preserve dashboards, home navigation, insights, popular/recent items, org settings, user settings, deployment service boundaries, logs, backups, monitoring, and production operations.

Implementation Decisions

• The new project starts as documentation and PRDs before large implementation work.
• Existing legacy repos remain read-only.
• Hetzner deployment should be container-first.
• PostgreSQL should be the primary relational data store unless a later decision says otherwise.
• Object/media storage must be adapter-based so the old Azure/GCP assumptions do not leak into the new service layer.
• Generated controls/widgets must not execute arbitrary code in the main browser context.
• Secrets must not be stored as plaintext JSONB fields.
• Public endpoints must have session scoping, throttling, and abuse protection.
• Quota and billing state must be idempotent and transaction-safe.

Testing Decisions

• Every preserved domain gets parity tests against documented legacy behavior.
• Tests should verify product behavior, not old implementation details.
• Migration tests should verify that data can be imported or represented in the new schema.
• Browser tests are required for editor, runtime, upload, chat, billing, and public companion flows.
• API tests are required for auth, tenant boundaries, flow CRUD, billing, quotas, integrations, webhooks, and submissions.
• Operational tests are required for health checks, backups, restore, and restart behavior.

Out of Scope

• Editing blinkin-2-platform.
• Committing secrets or .env values.
• Blindly copying all old code.
• Starting Hetzner deployment before the platform shape and data ownership are clear.
• Removing old features without an explicit retirement decision.

Acceptance Criteria

1. The full legacy product is represented as PRDs.
2. Each PRD maps features to legacy source repos.
3. Each PRD names unsafe legacy patterns that must not be repeated.
4. Each PRD includes user stories and implementation decisions.
5. The project has a clear Hetzner deployment direction.
6. Future implementation can be split into small slices from these PRDs.