TED OS — Screen Map by Role (3 surfaces)
reference· designer · updated 2026-09-05 · source
Output of the 2026-06-13 strategy session. AI/product input for designing the portal → the Paper artboards (Designer) come out of this before coding.
Status:
reference— proposed inventory and specs, pending formalization as Paper artboards + plan. Complementstedos-screens.md(specs for the Phase 2 product screens) and builds on the business model (tedos-business-model.md) and the MVP plan §7/§8.
0. The three surfaces and the six roles
Superseded (ADR-017, 2026-08-31). This "three surfaces inside one apps/admin" model is the pre-ADR-017 proposal. The actual three-surface split that shipped is
apps/portal(primary tenant surface) /apps/console(operator platform) /apps/clients/comprender(retiring into portal) — seeknowledge/decisions/adrs/ADR-017-three-surface-architecture.md.apps/adminis now frozen. The role/screen inventory below is kept as design-intent reference, not current architecture.
All of TED OS lived in apps/admin under this proposal, split into three surfaces with distinct audiences:
| Surface | Who uses it | What it is |
|---|---|---|
| A · Operator Portal | Your side (agency) | The cockpit: clients, deals, builders, finance, kit |
| B · Builder Portal | The builder network | Bounties, earnings, training |
| C · Client OS | The end client | The product they operate (SaaS), on their domain |
The six roles
| Role | Side | Power summary |
|---|---|---|
| Superadmin (José) | Operator | God mode: kit, infra, domains, tenancy, finance, all clients and builders |
| Agency admin (right hand) | Operator | Operates clients, deals, builders, bounties, reports. Does not touch kit/infra/secrets |
| Administration staff | Operator | Back-office: finance, billing, payouts, onboarding, support |
| Builder | Builder | Only their own: bounties, earnings, training, profile |
| Client admin | Client | Manages their OS: users, config, subscription, domain. External |
| Client user | Client | Uses the OS day to day. External |
Surface-access matrix
| Role | Operator | Builder | Client |
|---|---|---|---|
| Superadmin | ✅ everything | ✅ view/manage | ✅ any instance (support) |
| Agency admin | ✅ (no infra/kit) | ✅ manage | ✅ limited support |
| Administration staff | ✅ (admin/finance) | 👁️ view payments | — |
| Builder | — | ✅ their own | — |
| Client admin | — | — | ✅ their company |
| Client user | — | — | ✅ usage |
Conventions (apply to ALL screens)
- 4 mandatory states: loading (skeleton, no spinner), empty, error (inline),
success —
frontend-guardrails.md. - Design system: semantic tokens only (no hex/
-[Npx]), HugeIcons for every UI icon, Cian = the only chrome accent, Azafrán brand only (foundation-ui-conventions.md,color-scope.md,icons.md). - Layout: Grid System v2 — widget-based dashboards grouped by volatility; sidebar
w-18/60/80+ 64px header (grid-system.md). - Auth: Clerk Organizations — 1 org = 1 client; builders and internal team as members with their role (MVP plan §8).
- Responsive: collapses to 1 column under
md:, no horizontal scroll.
A · Operator Portal (your side)
Roles: Superadmin · Agency admin · Administration staff.
| Screen | Purpose | Key components | Access |
|---|---|---|---|
| A1 · Cockpit | At-a-glance command view | Metrics strip (clients, MRR, deals, builds), live feed, issues + owners, upcoming reports/payments, alerts | Superadmin + Agency admin (trimmed for admin staff) |
| A2 · Clients | All clients and their OS | List (client·status·plan·MRR·domain·next report) + detail (instance, subscription, team, reports); create client, invite admin, domain | Superadmin + Agency admin (staff: billing) |
| A3 · Deals / Pipeline | Funnel and scope of each deal | Funnel prospect→closed; detail: scope, plan/wireframes, price, projected split, team, 50/50 milestones | Superadmin + Agency admin |
| A4 · Meetings → Plans | From the meeting to the plan | Upload/connect recording, async processing status, generated plan, editor, "convert into deal" | Superadmin + Agency admin |
| A5 · Builders | Manage the network | Roster (level·points·quality·load·earnings) + detail (history, assignments, training, intake); assign, promote, review | Superadmin + Agency admin |
| A6 · Bounties | Gamified engine (operator side) | Create bounty (type·points·payout·level·royalty), board (open/taken/review/closed), delivery review | Superadmin + Agency admin |
| A7 · Finance | The money, in and out | Revenue (impl + MRR), billing, builder payouts (split+bounties+royalties), common fund, margins (Claude API ≤17%) | Superadmin + admin staff (full); Agency admin partial |
| A8 · Kit / Skills | Tend the IP | Catalogue (version, provenance), asset intake queue, royalty tracking by reuse | Superadmin (full); Agency admin (intake review) |
| A9 · Reports | Weekly client reports | Generator/editor (MDX), sending, history, status by client | Superadmin + Agency admin |
| A10 · Config / Infra 🔒 | The dangerous knobs | Domains, tenancy/orgs, roles/permissions, secrets, feature flags, Clerk | Superadmin only (tenant boundary, §8) |
B · Builder Portal
Role: Builder. Sees only their own and what's assigned.
| Screen | Purpose | Key components |
|---|---|---|
| B1 · Home | Personal progress board | Level and points, earnings this month, upcoming payments, recommended bounties, ranking |
| B2 · Bounty board | Where they grab work | Bounties for their level, detail (specs·points·payout·deadline·royalty), "take"; locked ones with "what you're missing" |
| B3 · My work | What they have in progress | Active bounties, deliver, review status, feedback |
| B4 · My earnings | Full transparency | Split by deal, bounties collected, royalties by reuse, dividend (🔒 future), export for invoicing |
| B5 · Academy | Where they train and level up | Courses, progress, next-level requirements, graduation = first accepted asset |
| B6 · Submit asset | Feed the flywheel | Upload skill/component, specs, intake status, "accepted + accumulated reuse" |
| B7 · Profile | Their identity in the network | Badges, quality score, history, level; note: participation earned and non-transferable |
C · Client OS (the product)
C-Admin · Client admin screens
| Screen | Purpose |
|---|---|
| Company config | Data, branding within limits, domain |
| Users and roles | Invite/manage employees, permissions |
| Subscription and billing | Plan, monthly fee, invoices, payment method, export their data |
C-Usage · Client user screens (already specified in MVP plan §7 + tedos-screens.md)
| # | Screen | What it is | Role in demo |
|---|---|---|---|
| 1 | Status (Home Panel) | Metrics + feed + upcoming runs | Opens the demo |
| 2 | Agent (detail) | Profile: purpose, skills, history | Core |
| 3 | Automations | List + timeline with run states | The "live" moment |
| 4 | Skills (library) | Index of installed capabilities | Secondary |
| 5 | Builder drops (handoff inbox) | Assets from the network: review/accept | Proves the network |
| 6 | Memory (seed-field) | Client data as a phyllotaxis field | The closer |
Screen × role matrix (summary)
| Screen | Superadmin | Agency admin | Admin staff | Builder | Client admin | Client user |
|---|---|---|---|---|---|---|
| A1 Cockpit | ✅ | ✅ | ◐ | — | — | — |
| A2 Clients | ✅ | ✅ | ◐ | — | — | — |
| A3 Deals | ✅ | ✅ | — | — | — | — |
| A4 Meetings→Plans | ✅ | ✅ | — | — | — | — |
| A5 Builders | ✅ | ✅ | — | — | — | — |
| A6 Bounties | ✅ | ✅ | — | — | — | — |
| A7 Finance | ✅ | ◐ | ✅ | — | — | — |
| A8 Kit/Skills | ✅ | ◐ | — | — | — | — |
| A9 Reports | ✅ | ✅ | — | — | — | — |
| A10 Config/Infra | ✅ | — | — | — | — | — |
| B1–B7 Builder | ✅ | ✅ | 👁️ payments | ✅ | — | — |
| C-Admin client | ✅ | ◐ | — | — | ✅ | — |
| C-Usage (1–6) | ✅ | ◐ | — | — | ✅ | ✅ |
✅ full · ◐ partial · 👁️ read-only · — no access
Build prioritization (in phases, tied to the MVP plan)
| Phase | Trigger | Screens |
|---|---|---|
| 1 — First client | Now | C-Usage 1–3 + C-Admin · minimal Operator (A1, A2, A3, A9) |
| 2 — Builder cohort 1 | First client closed | Builder Portal (B1–B7) · A6 Bounties · A8 Kit intake · split in A7 |
| 3 — Scale | Stages 0–1 proven | A4 Meetings→Plans automated · royalties and dividend · A10 Infra · C-Usage 4–6 at full fidelity |
To be defined (José)
- Administration staff: do they see all the money or only billing/collections?
- Builder Portal: web only or mobile too?
- Meetings→Plans (A4): MVP phase 1 or phase 3?
- Client admin: configurable branding or fixed (controlled premium) in the MVP?
- Is any screen missing (support/tickets, notifications, public academy)?