# ServerAvatar v8 — Central Panel: Frontend Flow Documentation > **Status:** Flows written · Nothing built yet > **Last updated:** 2026-10-07 (frontend doc — backend changes are added only after Bhavik approves them) > **Owner:** Bhavik Jethwa (Pair 2) · Frontend agent: `central-app-2` · Backend partner: `central-api-2` This document describes **what the frontend builds**: every screen, what the user does on it, and where they go next. The **flow** follows ServerAvatar v7 (order of steps and where the user lands). The **rules** follow the backend team doc — where the two differ, the backend wins; where the backend says nothing, v7 is used. Screens are our own design, not a copy of v7. Prices, limits and plan details always come from the backend. ## Overview **What is V8 Central?** One web app where a ServerAvatar customer manages all their servers, websites, team and billing. Every server runs the open-source ServerAvatar panel (**OSS panel**); Central talks to each panel and shows everything in one place. **What problem it solves:** instead of opening each server's panel on its own, a customer sees and runs every server, site, team member and payment from one account — and existing ServerAvatar v7 users can move over with their features and ways of working kept. **User side and admin side** - **User side** — what customers use: sign up, account, organizations and team, plans and billing, servers, sites and databases. - **Admin side** — what the ServerAvatar team uses to run Central: plans, payments, users, settings. **In scope now** — what the backend doc already describes: sign-in (Phase 2), account (Phase 3), organizations & members (Phase 4), integrations (Phase 5), billing (Phase 6), plans (Phase 7), notifications & mail (Phase 11), plus the server screens that come from the OSS panel. **Not in scope yet / left out** - **Later phases** (backend doc: "their own phases"): support tickets, AI assistant, affiliate program; the **Servers phase** is not written yet. - **Left out on purpose:** API access (B3.13), confirmation timer, users creating managed servers. ### Main flows at a glance **Flow A — Sign up** (Flow A, U2) ```flow Sign up / Google / GitHub | name, email, password, robot check — or Google / GitHub Default organization | created automatically at sign-up (U3) Dashboard | Getting started: Add server → Create application → Install SSL (U10) · verify-email banner until the email is verified ``` **Flow B — Log in** (Flow B, U2) ```flow Log in | email + password, or Google / GitHub Authentication checks | new-IP approval only if IP whitelist is on and the IP is new · 2FA code if 2FA is on Dashboard | or the page first asked for ``` **Flow C — Add a server** (U13.2) ```flow Add server | email must be verified first Choose a way | Cloud provider · My own server · Connect a panel Fill in details | provider account, region, size · or IP + root password / one-line command · or panel address + key Review → Create | ✖ plan limit reached → Upgrade (U8.10) Progress | Creating → Installing → Ready / Failed (Retry) Connect your accounts here too? | add Git / storage, or Skip Server page | server menu (U13.4) ``` **Flow D — Change plan** (U8) ```flow Plans page | current plan + plan cards Choose this plan | ✖ downgrade blocked → card says what to remove first Change plan confirm | price, unused days back as credit, coupon, new end date → Enough credit: Confirm → plan updated | → Not enough credit: "Add $X credit first" → Pay (U8.9) ``` ### Symbols - `→` goes to · **✔** success · **✖** error or blocked. - Labels: `PAGE` · `MODAL` · `CONFIRM` · `TYPE-TO-CONFIRM` · `TOAST` (see U1.3). - **U13.2** = this doc (clickable) · **B7.12** = backend doc item (grey tag). ### Build status One table for every module. 🟢 **READY** = requirements complete, the frontend can start · 🟡 **WAITING ON BACKEND** = the backend doc doesn't cover it yet · 🔴 **NEEDS YOUR DECISION** = a product decision is open. The table is built from each module's own Status and Build lines, so it never disagrees with them. [[BUILD-STATUS-TABLE]] --- ## Implementation flow **How V8 Central is built, phase by phase.** Flow follows **ServerAvatar V7** (order of steps, navigation, behaviour) · rules follow the **backend doc** (Bx) · server and app screens reuse the **OSS panel** screens, reached through Central. Proposed 2026-10-06 — waiting on the decisions at the bottom. **Every phase runs the same way:** review V7 → review this doc → review the backend → plan → **Bhavik approves** → build → test → check on phone, tablet, desktop → check against the API → mark done → next phase. One phase at a time. ```flow Phase 0 — Foundation | app shell, theme, 8 languages, shared parts, API client Phase 1 — Authentication | sign up, log in, 2FA, Google / GitHub (U2) Phase 2 — Organization | switcher + current organization for every page (U3) Phase 3 — Account | 7 tabs + Notifications (U4, U5) Phase 4–5 — Members → Roles | invite → accept · View / Manage permissions (U6, U7) Phase 6–8 — Plans → Billing → Subscription | plans made by the admin, shown on /plans · add credit · change / pay / expiry (U8, U9) Phase 9 — Dashboard | overview + Getting started (U10) Phase 10 — Integrations + Backup Storage | organization level: cloud providers, Git accounts, backup storage (U11, U12) Phase 11–12 — Servers → Server panel | connect a panel first · OSS screens (U13, U15) Phase 13 — Applications | OSS screens (U14) Phase 14–15 — Blueprints → Audit log | (U16, U17) ``` | Phase | Module | Depends on | Status | |---|---|---|---| | 0 | Foundation | — | 🟢 READY | | 1 | Authentication (U2) | 0 | 🟡 WAITING ON BACKEND | | 2 | Organization (U3) | 1 | 🟡 WAITING ON BACKEND | | 3 | Account + Notifications (U4, U5) | 1 | 🟡 WAITING ON BACKEND | | 4 | Members (U6) | 2 | 🟡 WAITING ON BACKEND | | 5 | Roles & permissions (U7) | 4 | 🔴 NEEDS YOUR DECISION (list not published, open question 8) | | 6 | Plans — view (U8): the plans the **admin creates** (A4) are shown on `/plans` | 2, 5 · Admin plans (A4) — mock plans until A4 exists | 🟡 WAITING ON BACKEND | | 7 | Billing (U9) | 6 | 🟡 WAITING ON BACKEND | | 8 | Subscription — change, pay, expiry (U8) | 6, 7 | 🟡 WAITING ON BACKEND | | 9 | Dashboard (U10) | 2, 8 | 🟡 WAITING ON BACKEND | | 10 | Integrations + Backup Storage — **organization level** (U11, U12) | 2, 7 | 🟡 WAITING ON BACKEND | | 11 | Servers (U13) — cloud servers use the providers from Phase 10; "Connect a panel" works without one | 2, 7, 8, 10 | 🟡 WAITING ON BACKEND | | 12 | Server panel + Databases (U13.4, U15) | 11 | 🟡 WAITING ON BACKEND | | 13 | Applications (U14) — Git accounts and backup storage come from Phase 10 | 12, 10 | 🟡 WAITING ON BACKEND | | 14 | Blueprints (U16) | 13 | 🟡 WAITING ON BACKEND | | 15 | Audit log (U17) | 2 | 🟡 WAITING ON BACKEND | | Later | Add-ons, Referral, Tags (U18–U25) · Admin side (A1–A12; A4 Admin plans is needed by Phase 6) | after 15 | — | ### Phase 0 — Foundation - **Screens:** sidebar (V7 order, U1.1), top bar, breadcrumbs, phone drawer, all system states (U1.5: loading, session expired, 403, 404, 500, offline, maintenance, too many requests), empty-state pattern (U1.7), test-state switcher (U1.8), permission check helper using the draft map (U1.6). - **APIs:** none — shared API client and sign-in handling only. - **States:** loading · empty · error · not found · signed out → Log in → back. - **Routes:** every path in **Page paths & navigation**, with separate server and app sidebars. - **Build:** reuse the OSS panel shell, table kit, forms, error helpers and `can()` permission check (same stack); theme; 8 languages without language in the address; token kept server-side (never in the browser). - **Test:** unit tests + browser tests at 320 / 768 / 1280 px. **Next:** Phase 1. Phases 1–15: screens, rules and flows are in each module (U2–U17); the table above gives the order and status. ### Done when — every phase A phase is finished only when **all** of these are true: 1. Every page path of the phase opens (Page paths & navigation). 2. Every flow in its module can be clicked from start to end on mock data. 3. Every screen state in its module, the system states (U1.5) and empty states (U1.7) can be shown with the test-state switcher (U1.8). 4. Items are hidden / read-only exactly as the permission map says (U1.6). 5. No hard-coded text — every word comes from the language files. 6. Works at 320, 768 and 1280 px, light and dark, by keyboard. 7. Build, lint and tests pass. 8. Bhavik has checked it and signed it off. | Phase | Also done when | |---|---| | 0 Foundation | Both sidebars, top bar, phone drawer; all system states (U1.5); test-state switcher works; every sidebar item opens (placeholder if not built) | | 1 Authentication | Flows A–H with their error paths; banner on every page until verified; back to the asked page after log in | | 2 Organization | Switcher reloads every page; My organizations + Shared with me; default never deletable; transfer + accept | | 3 Account + Notifications | All 7 account tabs; channels add / test / edit / delete | | 4 Members | Invite → Accept; pending invites; change role; remove; leave | | 5 Roles | View / Manage matrix (draft list, U1.6); a role change hides / shows items at once | | 6 Plans | Admin-created plans (mock) on `/plans`; trial / active / expired / locked shown | | 7 Billing | All billing tabs incl. **Managed plan** (shown only with managed servers; credit-run-out banner); add credit success / failed / processing | | 8 Subscription | Change plan, downgrade blocked reasons, cancel / resume, expiry banners, locked page | | 9 Dashboard | Getting started ticks + counters; current organization only | | 10 Integrations + Backup Storage | Cloud providers, Git, storage; Backups page (`/backups`, no deleted-server backups) | | 11 Servers | All add-server ways; Servers + Shared with me tabs; badge + filter; plan limit → Upgrade | | 12 Server panel + Databases | Every server menu item as listed; hidden by permission; unreachable state | | 13 Applications | Per-server list (9 columns); create; every app menu item | | 14 Blueprints | List, create, edit (Central-owned) | | 15 Audit log | List + filters | ### V7 vs V8 — intentional differences The sign-up → Dashboard flow follows ServerAvatar V7 step by step, **except for the rows below**. Same as V7 (no difference): **email notifications** for account, billing and plan; **server transfer** (admin-only). These are **confirmed V8 decisions** (re-confirmed by Bhavik, 2026-10-07). They are **not** gaps and must **not** be switched back to V7. In the flows they are marked 🔷. | # | Step | V7 | V8 (final) | Decided | |---|---|---|---|---| | D1 | Sign up | Optional "About you" questions (company size, industry, experience, how you heard about us) | **Not asked** — the form has name, email, password and the robot check only | Bhavik, 2026-10-06 | | D2 | First organization | User creates it after sign-up | **Created automatically** at sign-up (the user's default / personal organization); **never deletable**; more can be created later | Bhavik, 2026-10-05 | | D3 | Plan after sign-up | User picks a plan | **Trial starts automatically** (B7.6), no plan screen; plans are picked **later** from `/plans` | Bhavik + backend | | D4 | Invite sign-up | Joins the organization automatically | **Must press Accept** on the invite page (also existing users) | Backend B4.3 | | D5 | Applications list | Per server, **plus** an organization-wide "all applications" list | **Per server only** — Servers → server → Applications; no `/applications` page in the main sidebar | Bhavik, 2026-10-07 | | Managed servers | Users create them | Users can't | Bhavik, 2026-10-05 | | Server and app screens | V7's own panel | OSS panel screens through Central | Backend Phase 10 | | D6 | Deleted servers, deleted-server backups, restore to another server | V7 has them | **Not in V8** | Bhavik, 2026-10-07 | | D7 | Log Monitoring | Separate InsightHub service | **Handled by the Central Panel** | Bhavik, 2026-10-07 | ### Waiting on your decision 1. Reuse the OSS panel's frontend code (no licence file in the repo). 2. "Connect a panel" as the first way to add a server. 3. Who builds the shared foundation with Frontend 1 · token kept in a secure server-side cookie. --- ## Page paths & navigation **Where every main screen lives, before Phase 0 starts.** Paths have **no language part** (U1.1). `{server}`, `{app}`, `{database}`, `{user}`, `{token}` are ids from the backend. Pop-ups (`MODAL`, `CONFIRM`) have no path of their own — they open on top of the page they belong to. Tabs use their own path so they can be linked and bookmarked. ### Sign-in pages (no sidebar, language switcher on every page) | Path | Screen | Module | |---|---|---| | `/login` | Log in | U2 Flow B | | `/register` | Sign up (referral / affiliate / invite / lifetime code read from the link) | U2 Flow A, G, H | | `/login/two-factor` | Enter 2FA code / backup code | U2 Flow B | | `/auth/{provider}/callback` | "Signing you in…" (Google, GitHub) | U2 Flow C | | `/set-password` | Set a password (new Google / GitHub user, optional) | U2 Flow C | | `/forgot-password` | Forgot password | U2 Flow D | | `/reset-password/{token}` | Reset password | U2 Flow D | | `/verify-email/{token}` | Email verified / link not valid | U2 Flow A | | `/invite/{token}` | Accept invite (must press **Accept**) | U2 Flow E | | `/lifetime-deal` | Lifetime deal plans after sign-up | U2 Flow H | | `/account-locked` | Locked account (only billing reachable) | U8 | No plan-selection page at sign-up — the trial starts by itself (B7.6); plans are picked later from `/plans`. 🔷 Intentional V8 difference from V7 (D3). No "About you" page either (D1). ### Main app — sidebar (V7 order, U1.1) | Path | Screen | Module | |---|---|---| | `/dashboard` | Dashboard + Getting started | U10 | | `/servers` · `/servers/shared` | Server list — tabs **Servers** (this organization) · **Shared with me** (servers shared with me) | U13 | | `/servers/add` | Add server — pick a way | U13.2 | | `/servers/add/connect` · `/servers/add/command` · `/servers/add/ssh` · `/servers/add/cloud` | Connect an OSS panel · install command · root password · own cloud account (no managed option for users) | U13.2 | | `/servers/{server}/installing` | Install progress (Retry / Delete) | U13.2 | | `/blueprints` | WordPress blueprints (owned by Central) | U16 | | `/organizations` · `/organizations/shared` | Organizations — tabs **My organizations** · **Shared with me** | U3 | | `/members` | Members · `/members/invites` pending invites | U6 | | `/roles` · `/roles/new` · `/roles/{role}` | Roles, create, edit | U7 | | `/integrations` → `/integrations/git` | Integrations (organization level): cloud providers · Git accounts | U11 | | `/backup-storage` | Backup Storage (organization level) | U12 | | `/backups` | **Backups** — all backups of this organization's servers and apps in one list (v7) | U12 | | `/plans` | **Plans — its own main page** (current plan, plan cards, compare, redeem code); also the "Choose plan" page when a trial ends | U8 | | `/billing` → `/billing/wallet` · `/billing/transactions` · `/billing/usage` · `/billing/managed` · `/billing/auto-recharge` · `/billing/cards` · `/billing/profile` | Billing tabs (Overview is `/billing`) | U9 | | `/add-ons` | Add-ons | U18 | | `/audit-log` | Organization audit log | U17 | ### Top bar and user menu | Path | Screen | Module | |---|---|---| | — (menu) | Organization switcher · Theme · Language | U1.1, U3 | | `/notifications` | Notifications (bell → View all) + channels | U5 | | `/account` → `/account/security` · `/account/password` · `/account/ip-whitelist` · `/account/login-history` · `/account/activity` · `/account/settings` | Account tabs (Account information is `/account`) | U4 | | `/referral` | Referral | U24 | ### Server panel — opens with its own sidebar (`/servers/{server}/…`) | Path | Screen | Module | |---|---|---| | `/servers/{server}` | Server dashboard | U13.4 | | `…/applications` · `…/applications/create` | Applications list · Create application | U13.4, U14 | | `…/databases` · `…/databases/{database}` | Databases | U15 | | `…/system-users` | System users | U13.4 | | `…/firewall` | Firewall | U13.4 | | `…/cron-jobs` | Cron jobs | U13.4 | | `…/fail2ban` | Fail2ban (server) | U13.4 | | `…/logs` | System logs | U13.4 | | `…/services` | Services | U13.4 | | `…/php` · `…/node` | PHP · Node.js | U13.4 | | `…/settings` | Settings (server, access & security, memory, updates & restart, alert limits) | U13.4 | | `…/disk-cleaner` | Disk cleaner | U13.4 | | `…/backups` → `…/backups/history` · `…/backups/restores` | Backups | U13.4 | | `…/activity-log` | Server activity log | U13.4 | | `…/sync` | Server sync | U13.4 | ### Application panel — opens with its own sidebar (`/servers/{server}/applications/{app}/…`) | Path | Screen | Module | |---|---|---| | `…/{app}` | App dashboard | U14.4 | | `…/domains` | Domains & SSL | U14.4 | | `…/environment` | Environment (.env) | U14.4 | | `…/workers` | Workers | U14.4 | | `…/files` | Files | U14.4 | | `…/logs` | Logs | U14.4 | | `…/backups` | Backups (this app) | U14.4 | | `…/password-protection` | Password protection | U14.4 | | `…/firewall` | Web firewall | U14.4 | | `…/bot-blocker` | AI bot blocker | U14.4 | | `…/fail2ban` | Fail2ban (site login) | U14.4 | | `…/clone` | Site clone | U14.4 | | `…/deployment` · `…/php` · `…/staging` | Only for Git apps · PHP apps · WordPress | U14.4a | ### Admin side (`/admin/…`, admin role only) | Path | Screen | Module | |---|---|---| | `/admin` | Admin dashboard | A1 | | `/admin/users` · `/admin/users/{user}` | Users | A2 | | `/admin/payment-gateways` | Payment gateways | A3 | | `/admin/plans` | Plans | A4 | | `/admin/payments` | Payments & receipts | A5 | | `/admin/settings` | Platform settings | A6 | | `/admin/promo-codes` | Promo codes (pending decision) | A7 | | `/admin/organizations` · `/admin/servers` | Organizations & servers | A8 | | `/admin/affiliate` | Affiliate program | A9 | | `/admin/activity-log` | Activity log | A10 | | `/admin/staff-roles` | Staff roles (pending decision) | A11 | | `/admin/panel-health` | Panel health (pending decision) | A12 | ### Server panel and Application panel navigation Like V7, a server and an app each get **their own sidebar**; the main sidebar is replaced while you are inside them. ```flow Main sidebar | Dashboard · Servers · Blueprints · Organizations · Members · Roles · Plans · Billing · Add-ons · Audit log Server panel sidebar | opens on a server · "← All servers" at the top · 16 items in the U13.4 order Application panel sidebar | opens on an app · "← Server name" at the top · U14.4 items (+ type-only items) ``` 1. **Servers → click a server** → `/servers/{server}`: the **server sidebar** replaces the main sidebar. Its header shows the server name, status (online / offline), IP with Copy, and a **server switcher** to jump to another server on the same page. 2. **Server sidebar → Applications → click an app** → `/servers/{server}/applications/{app}`: the **app sidebar** replaces the server sidebar. Its header shows the app name, primary domain (Visit site) and an **app switcher** for other apps on this server. 3. **Back:** "← All servers" (server sidebar) and "← Server name" (app sidebar) at the top; breadcrumbs always show the full path: **Servers › server › Applications › app › page**. 4. **Hidden, never disabled-and-empty:** items the role can't view (B10.22), items the server can't run (OSS `/server/capabilities`, e.g. Node.js on a PHP-only server) and type-only app items (Deployment, PHP, Staging) are not shown. 5. **Phone:** each sidebar becomes the drawer; the switcher stays in the header. 6. **Server not reachable:** the sidebar stays, the page shows the offline state with Retry (exact screen open — backend Q3). ### Pending — not in the backend doc or OSS yet | Feature | V7 | Backend / OSS today | Status | |---|---|---|---| | Site migration (`/servers/{server}/site-migration`) | Yes | Not in the frontend doc yet | **Pending** — open question 18 | No path, screen or flow is written for this until Bhavik approves it. **Not in V8** (Bhavik, 2026-10-07): **Deleted servers + Restore**, **backups of deleted servers** and **restore a backup to another server** — v7 has them; V8 does not, so they are not pending any more. --- ## Decisions & open questions ### Confirmed decisions | Decision | Where | |---|---| | Flow follows ServerAvatar v7; rules follow the backend doc (backend wins); screens are our own design | whole doc | | No language in page addresses (`/dashboard` in every language); switcher on every page | U1.1 | | **Blueprints are owned and managed by Central** (Bhavik, 2026-10-06) | U16 | | Default organization is created automatically at sign-up; users can create more | Flow A, U3 | | Every invite must be accepted, also by existing users; links last 7 days | Flow E, U6 | | **Applications are shown per server only** (Server menu → Applications); no organization-wide applications page (Bhavik, 2026-10-07) | U14 | | Organization shares and server shares appear as **Shared with me** tabs; everything is shown by permission (Bhavik, 2026-10-07) | U3, U13, U1.6 | | **Transfer server is admin-only** (Admin → Servers, A8); users have no Transfer button (Bhavik, 2026-10-07) | A8 | | Organization-wide **Backups** page (`/backups`, v7) in the sidebar after Backup Storage (Bhavik, 2026-10-07) | U12 | | **Not in V8:** Deleted servers + Restore, deleted-server backups, restore to another server (Bhavik, 2026-10-07) | U12, Page paths | | **Email is the primary notification method**: account, billing and plan notifications by email only; extra channels (Slack, Telegram…) only for server and app events; no new extra emails (Bhavik, 2026-10-07) | U5 | | **Server transfer works as in v7**: admin-only, from the admin panel; no user Transfer button and no user request flow (Bhavik, 2026-10-07) | U13, A8 | | **Log Monitoring is handled by the Central Panel**, not by the OSS panel (Bhavik, 2026-10-07) | U21 | | **Features whose code is commented out (switched off) in v7 are not in V8** — global / quick search, user invoices and monthly invoice billing (due day, grace period, invoice prefix), self-managed server reminders, server default-PHP setting (Bhavik, 2026-10-07) | whole doc, A6 | | **Sign-up differences from V7 are intentional and final** (D1–D4: no About you, auto-created organization, automatic trial with plans later on `/plans`, invite needs Accept) — don't switch back (Bhavik, 2026-10-07) | Implementation flow → V7 vs V8 | | One role per member; transfer ownership and leave organization kept | U3, U6 | | The **default organization can't be deleted** | U3 | | Share a server = email + designation + permissions for that server + accept | U3 | | Inside an organization the **organization owner's** plan applies; members never buy a plan | U8 | | Cloud providers belong to the organization; Git accounts and backup storage are added to each server and listed at organization level | U11, U12 | | **Build order:** Members & Roles are built **before** Plans & Billing; **Integrations + Backup Storage are organization-level** and built as their own phase before Servers — not part of Servers or Applications (Bhavik, 2026-10-07) | Implementation flow | | **Plans are created by the admin** (Admin plans, A4); users see those plans on `/plans` (U8) (Bhavik, 2026-10-07) | U8, A4 | | Users **can't create managed servers**; existing managed servers keep working | U13.2 | | On a **managed server** the user **can't open the OSS panel** — it is managed only from Central (Bhavik, 2026-10-07) | U13 | | Add server ways: Cloud provider · My own server (root password yes / no) · Connect a panel; no database-engine field | U13.2 | | Delete account = password + optional reason; blocked by negative balance or servers | U4 | | Notification channels: Email, Telegram, Slack, Discord, Pushover, Webhook | U4 | | Getting started = Add server → Create application → Install SSL, with Skip | U10 | | Referral follows v7 until the backend writes it (invalid code stops sign-up, credit at sign-up, affiliate code wins) | Flow G, U24 | | Plans are dynamic (admin-managed); no fixed names, prices or limits | U8, A4 | | Blueprints and Premium Hosting Care for every user; other add-ons by plan | U16, U18 | | Server menu and app menu order fixed (from the OSS panel) | U13.4, U14.4 | | After login the user returns to the page they first asked for | Flow B | | Left out on purpose: B2.9 tokens, B2.11 rate limits, B3.13 API access, confirmation timer | — | | New in V8 section added: Server tags | U25 | | **Lifetime deal sign-up** is included (v7 flow) | Flow H | ### ⚠️ Backend decision required (known conflicts) The frontend doc and the backend doc say different things here. This doc does **not** pick an answer for the backend; it records what each side says and will be updated when the backend doc changes. | Topic | This doc currently shows | Backend doc says | |---|---|---| | Managed servers | Users **can't** create them (Bhavik, 2026-10-05) | B6.9: users can create a managed server | | Default organization | Created **automatically** at sign-up (Bhavik, 2026-10-05) | Phase 2 / B4.1: **not** auto-created, the user creates the first one | | Account activation | Logged in **straight away**, verify-email banner (v7 — Bhavik: sign-in = v7) | B2.2: account **inactive until the email is verified** | | Onboarding questions | **Not asked** anywhere (Bhavik, 2026-10-06) | B2.1: optional onboarding questions at sign-up · B3.2: edited in the profile | ### Open questions | # | Question | Waiting on | Impact (blocked) | Status | |---|---|---|---|---| | 1 | Backend **B6.9** still lets users create managed servers; we decided they can't. Remove B6.9 or say who creates them (D-36) | Backend | U13.2 | Open | | 2 | Backend Phase 2 / **B4.1** still say organizations are **not** auto-created (D-2) | Backend | Flow A, U3 | Open | | 3 | Sign-up: backend **B2.2** keeps the account inactive until the email is verified; our flow (v7) logs the user in straight away (D-26) | Backend | Flow A | Open | | 4 | Managed servers at migration: who installs the OSS panel on them, trial timings | Your decision + backend | U13, U9 | Open | | 5 | After a trial, may the user pick the **Free** plan? (D-33) | Backend | U8 | Open | | 6 | Admin lowers a limit below what a user already uses (D-34) | Backend | U8, A4 | Open | | 7 | Managed-server expire date when the server's panel can't be reached (D-35) | Backend | U13, U9 | Open | | 8 | Permission list for roles not published yet ("a separate step", backend Phase 4) | Backend | U7 | Open | | 9 | "Update everywhere" when servers hold different tokens (D-30) | Backend | U11 | Open | | 10 | Servers phase not written yet (server details, connecting a server, own-server install — D-13) | Backend | U13 – U15 | Open — adding a server is written (B8); server panel features not taken into this doc yet | | 11 | No backend phase yet for Dashboard, Blueprints, Add-ons (WP Toolkit: D-15), Referral (D-23), Tags | Backend | U10, U16, U18, U24, U25 | Open | | 12 | Where the **per-server Notifications screen** goes — the backend says "Server → Notifications" but the U13.4 menu order is fixed (D-37). | Your decision | U5, U13.4 | Open | | 13 | Currency and tax rules (D-22) | Backend | U8, U9 | Open | | 14 | Can new users buy **lifetime** plans? The backend says "decided later"; Flow H follows v7 meanwhile | Backend | Flow H, U8 | Open | | 15 | Can a member with billing access **change the owner's plan**? U8.11 gives them pay buttons; U8 says members see limits, not a buy button | Your decision | U8 | Open | | 16 | Which of Frontend 1's extra items to add (navigation map, claim server, Supervisor, Docker, site migration, SFTP …) | Your decision | several | Open | | 18 | **Site migration** — V7 has it; parked by backend Phase 10 (v7-only, not in OSS). Add only when the backend covers it | Backend | Page paths (pending) | Open | --- **Resolved** | Question | Answer | Status | |---|---|---| | Can the default organization be deleted? | **No** — never deletable (Bhavik, 2026-10-05) | Resolved | | Who owns blueprints (D-14)? | **Central** manages them (Bhavik, 2026-10-06) | Resolved | | Does the language appear in page addresses? | **No** (Bhavik, 2026-10-05) | Resolved | | Deleted servers + Restore (was question 17), deleted-server backups, restore to another server? | **Not in V8** (Bhavik, 2026-10-07) | Resolved | | Does a new user get a trial or no plan? | **Trial starts automatically** at sign-up; the admin sets the days (backend B7.6) | Resolved | --- ## Who can do what Only permissions written in this doc — nothing guessed. **✔** yes · **✖** no · **Role** = only if their role gives that permission (the role permission list is **not defined by backend yet**, open question 8) · **Not defined by backend yet** = no rule written yet. | Action | Owner | Admin | Member | Shared user | Locked member | |---|---|---|---|---|---| | View servers and apps | ✔ | Role | Role | Only the shared server | ✖ (Locked page only) | | Add server | ✔ (email verified, within plan limit) | Role | Role | ✖ never | ✖ | | Manage a server | ✔ | Role | Role | Only what was given for that server | ✖ | | Delete server | ✔ (also when the plan has expired) | Role | Role | ✖ never | ✖ | | See Billing | ✔ | Role (billing access) | Role (billing access) | Not defined by backend yet | ✖ no billing tab | | Add credit | ✔ (also when locked) | Role (billing access) | Role (billing access) | Not defined by backend yet | ✖ ("Ask to add credit") | | Change plan | ✔ | ? see Open question 15 | ? see Open question 15 | Not defined by backend yet | ✖ | | Invite members | ✔ | Role | Role | ✖ | ✖ | | Change role / remove member | ✔ (owner's own row has no actions) | Role | Role | ✖ | ✖ | | Share a server | ✔ | Role | Role | ✖ never | ✖ | | Connect cloud providers, Git, storage | ✔ | Role | Role | Not defined by backend yet | ✖ | | See Audit log | ✔ | Role | Role | Not defined by backend yet | ✖ | | Rename / delete organization | ✔ owner only (never the default organization) | ✖ | ✖ | ✖ | ✖ | | Transfer ownership | ✔ owner only | ✖ | ✖ | ✖ | ✖ | | Transfer a server to another organization / user | ✖ — **ServerAvatar admins only** (A8) | ✖ | ✖ | ✖ | ✖ | | Leave organization | ✖ | ✔ | ✔ | Not defined by backend yet | Not defined by backend yet | | See **Organizations → Shared with me** | ✔ (organizations they joined) | ✔ | ✔ | ✖ | Not defined by backend yet | | See **Servers → Shared with me** | ✔ (servers shared with them by others) | ✔ | ✔ | ✔ only their shared servers | Not defined by backend yet | **Everything is shown by permission** (Bhavik, 2026-10-07): in organization shares and server shares, sidebar items, tabs, buttons and server / app menu items the user has **no view** permission for are **hidden**; with **view only**, the page opens read-only and the change buttons are hidden. A shared user sees only what was given for that server (B4.6). - **Plan expired:** everyone can still look, but only **Delete server** and **Add credit** work. - **Account locked:** the owner sees the **Locked** page with billing only; the owner's team is locked too (Locked member column). - **Owner and Admin** are fixed system roles that can't be edited; other roles use View / Manage permissions (U7). ## U1. Basics, journeys & pop-up rules **Status:** Applies to every screen **Build:** 🟢 READY — no backend needed for these rules **Depends on:** Nothing — build this first (layout, menus, pop-up rules, system states, permission map, empty states and test states used by every screen). ### U1.1 Basics - **Languages:** 8 (en, es, de, fr, pt, ja, ru, hi). No hard-coded text: every word comes from the language files. - **Language switcher:** on every page, **including the sign-in pages** → pick a language → the same page reloads in it. The choice is remembered. First visit: the browser language if supported, otherwise English. - **No language in the address:** page addresses are the same in every language (`/dashboard`, never `/en/dashboard`), like the OSS panel. A shared link opens in the reader's own language (Bhavik, 2026-10-05). - **Layout:** sidebar, top bar (organization switcher, bell, theme, user menu), breadcrumbs. Drawer on phones. - **Sidebar order:** Dashboard → Servers → Blueprints → Organizations → Members → Roles → Integrations → Backup Storage → Backups → Plans → Billing → Add-ons → Audit log. - **User menu order:** Account → Notifications → Referral → Theme → Log out. **Account** has tabs: Account information · Security & 2FA · Update password · IP whitelist · Login history · Activity log · Settings. - **Session:** stays logged in with secure cookies. Session ended → **Log in** page, and back to the same page after logging in. - **Forms:** fields are checked while typing. Server errors show under the field. - **Tables:** paging, sorting, empty state. Cards on phones. - **Works on:** phones (320 px) to large screens, keyboard and screen readers. ### U1.2 Journeys at a glance **New user** 1. Sign up, or Google / GitHub (U2.1, U2.4) → default organization made automatically (U3.4) → Dashboard (U10) 2. Getting started: Add server (U13.2) → Create application (U14.2) → Install SSL (U14.4) 3. Optional: invite team (U6), set roles (U7) **Returning user** 1. Log in (U2.3) → new-IP check if IP whitelist is on (U2.8) → 2FA if on (U2.7) 2. Last used organization opens → Dashboard **Invited user** 1. Invite email → **Accept invite** page (U2.6) 2. Logs in, or signs up with the code filled in → **Accept** → lands in that organization's Dashboard **Lifetime deal user** (Flow H) 1. Lifetime deal link → Sign up → **Lifetime deal** page 2. Add credit if needed → pick a lifetime plan → Dashboard (no renewals) **Referred user** 1. Referral link → Sign up with the code filled in (Flow G) 2. Same as a new user → sign-up credit is added at once ### U1.3 Pop-up rules | Label | What it is | Use it for | |---|---|---| | `PAGE` | **Page** | Lists, details, long forms, step-by-step wizards | | `MODAL` | **Modal** (pop-up with a form) | Short forms, up to about 5 fields. Closes with ✕, Cancel or Esc | | `CONFIRM` | **Confirm** ("Are you sure?") | Delete, remove, disconnect, stop, cancel, pay. Danger button is red. Nothing happens until it's clicked | | `TYPE-TO-CONFIRM` | **Type to confirm** | Big deletes: the user types the name before the red button works | | `TOAST` | **Toast** | Short message after something worked ("Saved") | - On phones, modals open as a sheet from the bottom. - Only one pop-up at a time. A confirm can open on top of a modal. - Closing a modal with unsaved changes → `CONFIRM` "Discard changes?" - Every `TYPE-TO-CONFIRM` shows a short **"What will happen"** box with real numbers (for example "3 applications and 2 databases will stop"). - **Delete protection** (U4.6) on → every delete button is off and shows "Delete protection is on" with a link to Account → Settings. ### U1.4 Checks before every action When a user clicks an action (for example **Add server**), the frontend checks in this order and shows the **first** message that applies. Each check is already defined in its own section; this table only fixes the order. | # | Check | What the user sees | Defined in | |---|---|---|---| | 1 | Not logged in | **Log in** page, then back to the page they asked for | Flow B | | 2 | Email not verified | "Please verify your email address." + Resend | Flow A step 4 | | 3 | Account locked | **Locked account** page (only billing reachable; members see the owner's name) | U8 step 8 | | 4 | Plan expired | Button off: "Plan has expired. Please renew it" | U8 step 7 | | 5 | Role has no permission | Button off, with the reason | U7 | | 6 | Over the plan limit | **Upgrade** `MODAL` — only the owner gets **Pay** | U8.10, U8.11 | ### U1.5 System states (every page) One look for each state, used everywhere. The page keeps its sidebar and top bar unless noted. | State | When | What the user sees | Action | |---|---|---|---| | Loading | Data on its way | Skeleton in the page's own shape (rows, cards) — no blank page | — | | Session expired | Signed out while working | **Log in** page (no sidebar), message "Your session has ended. Please log in again." | Log in → back to the same page | | No permission (403) | Opening a page or item the role can't view (U1.6) | "You don't have access to this page." + who to ask (organization owner) | **Go to dashboard** | | Not found (404) | Wrong address, deleted item, or an item from another organization | "This page doesn't exist or was removed." | **Go to dashboard** / **Back** | | Server error (500) | Something failed on our side | "Something went wrong. Please try again." | **Try again** | | No internet | The browser is offline | Bar at the top "You're offline — changes won't be saved." Buttons that save are off | Disappears when back online | | Maintenance | Central is under maintenance | Full page (no sidebar) "We're doing maintenance. Back soon." | **Refresh** | | Too many requests | Rate limit reached | `TOAST` "Too many requests. Please wait a moment and try again." | Try again later | | Server unreachable | A server or its panel doesn't answer | Inside the server panel only — see U13 "Offline / unreachable server" | **Retry** | - The exact wording goes into the language files; keys to be defined (Messages reference). - A state never hides the page's own unsaved form: the form stays filled after **Try again**. ### U1.6 Permission map (draft) Which permission shows each part of the app. **Draft taken from v7's permission list** (90 permissions in 8 groups: organization, dashboard, server, application, database, backup, firewall, cron job / application user). It is replaced by the backend's list when it is published (open question 8). Nothing here changes the confirmed rules in **Who can do what**. **Rule for every row:** no **view** → the item is **hidden** (menu item, tab, card, button) · **view only** → the page opens read-only, change buttons hidden · **manage** → everything on the page. Owner always has everything. A shared user gets only what was given for that one server (B4.6). | Area | Shown when (v7 permission) | Manage covers | |---|---|---| | Dashboard | dashboard | — (view only) | | Servers list · server page | servers · server panel | Restart, settings, alerts | | Add server | server · create | — | | Delete server | server · delete | — | | Transfer server | **Never on the user side** — no permission can turn it on; admin panel only (A8) | — | | Share server | server · share server | Invite, edit permissions, remove | | Server menu items | server · applications / databases / application users / firewall / fail2ban / cron jobs / logs / settings / disk cleaner / activity log … (one per item) | Create / delete inside that item (e.g. firewall · create, database · delete) | | Applications (per server) | server · applications | application · create / delete | | App menu items | application · dashboard / file manager / SSL / PHP settings / logs / Git / WP Toolkit … (one per item) | Changes inside that item | | Databases | server · databases | database · create / phpMyAdmin / remote access / delete | | Backups (server, app, `/backups`) | dashboard · backups (archive: archive backups) | backup · create / download / restore / delete | | Organizations | organization · basic details | Rename, delete, transfer: **owner only** | | Members | organization · members | Invite, change role, remove | | Roles | organization · role & permissions | Create, edit, delete roles | | Integrations — cloud providers | organization · cloud platforms | Connect, edit, disconnect | | Integrations — Git | organization · git | Connect, update, remove | | Backup Storage | organization · cloud storage | Add, test, edit, remove | | Plans | organization · plan (owner by default in v7) | Change plan — open question 15 | | Billing | organization · usage summary (billing access) | Add credit, cards, auto-recharge | | Add-ons | organization · active services | Buy, cancel | | Audit log | organization · activity log | — (view only) | | Blueprints | Not in v7's list — **not defined by backend yet** | — | | Referral, Account, Notifications | Personal — always shown to the signed-in user | — | ### U1.7 Empty states (first-time user) Every list page has an empty state with one clear next step. Filters with no results show "No results — Clear filters" instead. | Page | Message | Next step | |---|---|---| | Dashboard | Getting started box | Add server | | Servers | "No servers yet" | **Add server** | | Servers → Shared with me | "No server is shared with you yet." | — | | Applications (in a server) | "No applications on this server yet" | **Create application** | | Databases | "No databases yet" | **Create database** | | Organizations → Shared with me | "No organization is shared with you yet." | — | | Members | Only the owner row + "Invite your team" | **Invite member** | | Roles | Owner and Admin (fixed) + "Create a role for your team" | **Create role** | | Integrations | "No cloud provider connected" / "No Git account connected" | **Connect provider** / **Connect Git** | | Backup Storage | "No backup storage yet" | **Add storage** | | Backups | "No backups yet" (no storage → "Connect backup storage first") | **Go to servers** / **Backup Storage** | | Billing → Transactions | "No transactions yet" | **Add credit** | | Blueprints | "No blueprints yet" | **Create blueprint** | | Audit log | "Nothing has happened in this organization yet" | — | | Notifications | "You're all caught up" | **Add a channel** | If the role can't use the next step, the button is hidden (U1.6) and only the message shows. ### U1.8 Test states (developer state switcher) The frontend is built on mock data first. A **developer-only** switcher (never in production) sets the account to each state below, so every screen can be checked without the backend. | # | Test state | What the screens must show | |---|---|---| | 1 | Email not verified | Banner on every page + Resend; Add server blocked (Flow A step 4) | | 2 | Trial | Trial banner with days left; Plans shows "Trial" (U8) | | 3 | Trial ended / plan expired | Actions off "Plan has expired. Please renew it"; Choose plan (U8) | | 4 | Locked account | Locked page, only billing reachable; members see the owner's name (U8) | | 5 | Owner | Everything visible | | 6 | Admin, view-only role | Pages open read-only; change buttons hidden (U1.6) | | 7 | Member with no permission for an area | That sidebar item hidden; direct address → No permission (U1.5) | | 8 | Shared user (one server) | Only Servers → Shared with me + that server, only the given menu items (U13.1) | | 9 | Member of a shared organization | Organizations → Shared with me; switch → only the role's pages (U3) | | 10 | Empty organization | Every empty state (U1.7) and Getting started | | 11 | Over the plan limit | Upgrade modal on Add server / Create application (U8.10) | | 12 | Delete protection on | Every delete button off with the reason (U1.3) | | 13 | Each system state | Loading, session expired, 403, 404, 500, offline, maintenance, too many requests (U1.5) | --- ## U2. Sign up & login **Status:** Backend Phase 2 — requirements complete · Flow: ServerAvatar v7 **Purpose:** New and returning users get in safely: sign up, verify email, log in (email or Google/GitHub), 2FA and new-IP checks, reset password, accept invites, log out. **Opens from:** Public pages; Sign up / Log in links on the website. **Build:** 🟢 READY — backend Phase 2 complete. One item waits on the backend: the default organization made at sign-up (see Open questions) **Depends on:** Basics (U1). Backend Phase 2. **Permissions:** Public pages — no sign-in needed (except the 2FA and accept steps). **Open questions:** #2, #3, #14 #### Screens | Screen | What's on it | Type | |---|---|---| | Sign up | Name, email, password, robot check; referral / affiliate / invite code from the link | `PAGE` | | Log in | Email, password, Google, GitHub, Forgot password | `PAGE` | | Enter code | 6-digit 2FA code, resend, backup code | `PAGE` | | Forgot / Reset password | Email; then new password | `PAGE` | | Accept invite | Organization, inviter, role; Accept / Decline | `PAGE` | | Email verified | Result of the verify link | `PAGE` | | Set a password | New Google / GitHub users: new password + confirm, **Skip** | `PAGE` | | Lifetime deal | Lifetime plans: one-time price, server limit, how many are left | `PAGE` | #### Screen states - **Sign up** — sending → button spinner, fields locked · errors under each field ("The email has already been taken.", "Please verify you are not a robot") · Google / GitHub buttons hidden when the admin turned them off. - **Log in** — one generic message for a wrong email or password (B2.3) · banned → its own message (B2.3) · new IP with IP whitelist on → banner "Unauthorized IP — check your email to approve this IP" (approval link valid **24 h**, B2.8) · too many tries → rate-limit message (B2.11). - **Two-factor authentication** — wrong code → message, stays on the page · **5** wrong email codes → the code stops working, ask for a new one (B2.7) · backup code → one text field instead of the 6 boxes · the token is given **only after** this step passes (B2.7). - **Forgot password** — ✔ "Reset link sent to your email." · ✖ "This email is not registered." - **Reset password** — link valid **60 min** (B2.5) → expired: message + **Send a new link** · ✔ → Log in + `TOAST` "Password changed". - **Email verified** — link valid **24 h** (B2.2) · invalid or expired → message + **Resend verification link**. - **Set a password (new Google / GitHub user)** — follows v7; **not in the backend doc yet** (Flow C). - **Accept invite** — logged in → only the card + Accept / Decline · expired · already used · cancelled · logged in as someone else ("This invite is for name@example.com" + **Log out and switch**) — see Flow E. - **Lifetime deal** — no payment yet → "Please make a transaction before activating your account." + **Add credit** · sold out → card greyed "Sold out" · see Flow H. #### Flows ### Flow A — Sign up (U2.1, U2.2) 1. **Sign up** `PAGE` (B2.1) — user enters name, email, password (min 8) and passes the **Cloudflare Turnstile** robot check → **Create account**. - Referral, affiliate and invitation codes are filled in from the link (B2.1). - 🔷 **Intentional V8 difference from V7** (D1) — no "About you" questions on this page. - ✔ Account created and **logged in straight away** → default organization (step 2) → **Dashboard** (step 3). - Or **Google / GitHub** (Flow C). - ⚠️ **Backend decision required** — this follows v7 (Bhavik: sign-in = v7); backend B2.2 keeps the account **inactive until the email is verified**. Update when the backend doc changes. - ✖ Field errors under each field (email taken, work email needed, robot check) → stays on the page. 2. **No organization step:** - 🔷 **Intentional V8 difference from V7** (D2, D3) — V7 makes the user create the first organization and pick a plan; V8 does neither. - The user's **default organization** is created automatically at sign-up (U3.4). - The user lands in it and can rename it or create more organizations later (U3). - **Plan:** the backend starts the **trial** for every new user by itself (B7.6) — no plan screen. The user picks a plan later from `/plans` (U8). The trial length is set by the admin. When it ends the user must pick a paid plan (U8.8). - ⚠️ **Backend decision required** — this doc follows Bhavik's decision (created automatically); backend Phase 2 / B4.1 say organizations are **not** auto-created. Update when the backend doc changes. 3. **Dashboard** (U10) — the **Getting started** box guides the user: **Add server** → **Create application** → **Install SSL**. - Signed up from an invite → **Accept invite** (Flow E) instead. 4. **Verify email** (U2.2) — until verified, every page shows the banner "Please verify your email address." + **Resend** → `TOAST` "Verification link sent". - Adding a server is blocked until verified ("Please verify your email address."). - Email link (valid **24 h**, B2.2) → **Email verified** `PAGE` → **Go to dashboard**. Link not valid or expired → message + **Resend**. ### Flow B — Log in (U2.3, U2.7, U2.8) 1. **Log in** `PAGE` (B2.3) — email + password → **Log in**. Links: Forgot password, Sign up, Google, GitHub. - ✖ Wrong email or password → one generic message under the form. Account banned → its own message. Too many tries → rate-limit message (B2.11). - Every login is saved in **Login history** (IP, browser — Account, U4.11). 2. **New IP?** (U2.8) — **only when the user has turned on IP whitelist** (Account → IP whitelist, U4.10) and this IP is not on their list (v7). Whitelist off → straight to step 3. Otherwise → message "Unauthorized IP — check your email to approve this IP". The approval link is valid **24 h** (B2.8). The user opens it to approve the IP, then logs in again → back to step 1. 3. **2FA on?** (U2.7, B2.7) → **Enter code** `PAGE`: 6-digit code from **Google Authenticator** or the **emailed code** (valid **10 min**). **Resend** after 60 seconds. "Use a backup code" link. - ✖ Wrong code → message, stays on the page. After **5** wrong email codes the code stops working → **Resend**. - The backend gives the sign-in token **only after** this step passes (B2.7). 4. ✔ Logged in → last used organization → **Dashboard**, or back to the page they first asked for. 5. **Staying signed in** (B2.9): the sign-in lasts **15 days** and is renewed quietly with the refresh token (valid **30 days**). If it can't be renewed → **Log in** page, then back to the page they were on. ### Flow C — Google / GitHub (U2.4) 1. **Log in** or **Sign up** page → **Google** or **GitHub** (only the switched-on ones show) → provider's page. 2. Back to **Signing you in…** `PAGE`. - New user → account created → **Set a password** `PAGE` (optional: new password + confirm → **Save** `TOAST`, or **Skip**) so they can also log in with email later → default organization → **Dashboard** (Flow A steps 2–3). - Follows v7 (a new Google / GitHub user gets a set-password link); not in the backend doc yet. Skipped → they can still use **Forgot password** later (Flow D). - Existing user (same email) → the Google / GitHub login is **linked automatically** (B2.4) → Flow B step 2 (new-IP and 2FA checks still apply). - ✖ Cancelled or failed → **Log in** with a message. ### Flow D — Forgot password (U2.5) 1. **Log in** → **Forgot password** → **Forgot password** `PAGE`: email → **Send link**. - ✔ "Reset link sent to your email." ✖ "This email is not registered." 2. Email link (valid **60 min**, B2.5) → **Reset password** `PAGE`: new password + confirm → **Reset**. - ✔ → **Log in** with `TOAST` "Password changed". The reset **logs out all devices** (B2.5). ✖ Link expired → message + **Send a new link**. ### Flow E — Invitation (U2.6, B4.3) **Everyone must accept**, including people who already have an account (backend rule). 🔷 **Intentional V8 difference from V7** (D4) — in V7 an invite sign-up joins the organization automatically; in V8 the user must press **Accept**. 1. Invite email → **Accept invite** `PAGE`: organization name, who invited them, their role. 2. Not logged in: - Has an account → **Log in** → back to **Accept invite**. - New person → **Create your password** on the same page: name + password (B2.6) → account created → back to **Accept invite**. 3. **Accept** → `TOAST` "You joined " → that organization's **Dashboard**. **Decline** → `CONFIRM` → their own default organization's Dashboard. 4. Other states on the same page: - **Expired** (links last 7 days) → "This invite has expired. Ask the organization for a new one." - **Already used** → "You've already joined" + **Open organization**. - **Cancelled** → "This invite was cancelled." - **Logged in as someone else** → "This invite is for name@example.com" + **Log out and switch**. 5. Open invites also show in the bell until accepted or declined. ### Flow F — Log out (U2.10) 1. User menu → **Log out** (no confirm) → the current sign-in token is revoked (B2.10) → **Log in** page. ### Flow G — Sign up from a referral link (U2.1, U24) Referral is not in the backend doc yet, so this follows v7. 1. Friend opens the **referral link** (U24) → **Sign up** `PAGE` with the **Referral code** filled in (read-only). 2. Banner on top: "Sign up and get **$X credit**." (amount from the backend). No banner when the referral program is off. 3. Name, email, password, robot check → **Create account**. Google / GitHub keep the code too. - ✖ Code not valid → sign-up stops with "Invalid referral code." 4. ✔ Account created → **$X credit is added at once** → `TOAST` "You received $X for signing up with a referral." → **Dashboard** (Flow A steps 2–3). - Link has both an affiliate and a referral code → the **affiliate** code counts. - Already has an account → normal **Log in**, no credit. ### Flow H — Lifetime deal sign-up (follows v7) ⚠ The backend says whether **new** users can buy lifetime plans is **"decided later"** (Phase 7). This flow follows v7 until then (Bhavik, 2026-10-05). 1. User opens the **lifetime deal link** (from the website's lifetime page) → **Sign up** `PAGE`, marked as a lifetime deal sign-up. Google / GitHub keep the mark too. 2. **Create account** → **Lifetime deal** `PAGE`. 3. **Lifetime deal** `PAGE`: the lifetime plans the admin offers — one-time price, server limit, and **how many are left** of each deal. 4. Pick a plan → **Buy**: - ✖ No completed payment yet → "Please make a transaction before activating your account." → **Add credit** `MODAL` (U9) → back to this page with the plan kept. - ✔ Payment done → **Confirm** `CONFIRM`: plan, one-time price paid from credit → `TOAST` → **Dashboard**. 5. The plan shows as **Lifetime**: no renewal date and no renewal banners (U8). - ✖ Other messages (v7): - "You are not eligible for a lifetime account." — the account didn't sign up through the lifetime deal link. - "You are not eligible for this plan." — the plan isn't offered to this account. - "Invalid plan." - The user already has their **default organization** (U3), so no extra organization is created (v7 made a "Personal" one here). --- ## U3. Organizations **Status:** Backend Phase 4 (Pair 1) — requirements complete **Purpose:** Every user gets a default organization at sign-up (made by the backend); users create more, switch, manage them, see the organizations **shared with them**, transfer ownership and share single servers. **Opens from:** Sidebar → Organizations; top-bar organization switcher → Manage. **Build:** 🟡 WAITING ON BACKEND — the backend still has to write the auto-created default organization (Phase 2 / B4.1) **Depends on:** Sign up & login (U2) — needs a signed-in user. Backend Phase 4. **Permissions:** Rename, delete and transfer ownership: owner only. The default organization can never be deleted. **Open questions:** #2 #### Screens | Screen | What's on it | Type | |---|---|---| | Organizations | Tabs **My organizations** · **Shared with me**; cards, list, create / edit / delete | `PAGE` | | Transfer ownership | Pick member + password + 2FA | `MODAL` | | Accept ownership | Password + 2FA, Accept / Decline | `MODAL` | | Share server | Email, designation, permissions | `MODAL` | #### Screen states - **Organization switcher (top bar)** — one organization → switcher still shows it with **Create organization** · switching → all screens reload for that organization. - **Organizations** — loading → skeleton rows · Delete off with the reason: default organization (never deletable) · has servers ("Please delete servers before deleting organization.") · not the owner (B4.2). - **Transfer ownership** — blocked → reason shown: unpaid charges · the new owner's plan doesn't fit (B4.7). - **Share server** — "This server has already been shared with this user." · "This user is already a member of the organization." · a shared user never gets create / delete / share (B4.6). #### Flows ### Flow — Default organization (U3.4) 1. **Sign up** → a **default organization** is created for the user automatically (letter avatar, no logo). There is **no "create your first organization" screen**. - 🔷 **Intentional V8 difference from V7** (D2) — V7 makes the user create the first organization. - ⚠️ **Backend decision required** — backend Phase 2 / B4.1 say organizations are **not** auto-created; this doc follows Bhavik's decision (2026-10-05). 2. The user lands in it right after sign-up → **Dashboard** (U10). 3. They can **rename** it (Edit, U3.5) and **create more** organizations any time (next flow). It stays the default until they set another one. - The **default organization can never be deleted** — its **Delete** button is off with the reason (Bhavik, 2026-10-05). 4. Edge case — the user has no organization at all (e.g. creation failed): show **Create your organization** `PAGE` (name + description → **Create**) instead of an empty app. ### Flow — Switch and manage (U3.1–U3.5) 1. Top bar **Switcher** (U3.1): my organizations + my role, default marked → pick one → all screens reload for that organization → its **Dashboard**. 2. **Switcher → Manage** → **Organizations** `PAGE` (U3.2): cards (total, I own, I'm in, servers), search, filter, sort, table. 3. **Create** `MODAL` (U3.3, B4.1): name + description (+ logo; a letter avatar is made if empty) → the creator is the **owner** → **Create** → `TOAST` "Your organization created successfully" → switched to it. 4. **Edit** `MODAL` (U3.5, owner only): name, description, logo → `TOAST`. **Set as default** → `TOAST`. 5. **Delete** → `TYPE-TO-CONFIRM` (U3.5, owner only). Blocked, with the reason on the button: - default organization (**never deletable**) · the only organization · "Please delete servers before deleting organization." - ✔ Deleted → `TOAST` → switched to the default organization. ### Flow — Organizations shared with me (U3.2) 1. **Organizations → Shared with me** tab (`/organizations/shared`): organizations the user **joined by accepting an invite** (Flow E) — name, owner, **my role**, servers count. 2. **Open** → switches to that organization; the sidebar and every page show only what **my role** allows (Who can do what). 3. Actions follow the role: no rename / delete / transfer (owner only) · **Leave organization** → `CONFIRM` → back to the default organization. 4. The top-bar switcher lists my organizations and shared ones together, each with my role. 5. Empty → "No organization is shared with you yet." ### Flow — Transfer ownership (U3.7, owner only) 1. **Organizations → Transfer ownership** `MODAL` (B4.7) → pick an **existing member** → **your** password (or email code) + **your** 2FA if on → **Send** → both see "expires in 48 hours". 2. The new owner sees it in the **bell**, the **email**, and a **banner** on every page → **Review** → **Accept ownership** `MODAL`: **their** password (or email code) + 2FA if on → **Accept** within **48 h**. Or **Decline** → `CONFIRM`. 3. ✔ Done → old owner becomes admin → `TOAST` for both. 4. ✖ Blocked → the reason (unpaid balance, plan too small). ### Flow — Share a server (U3.8) 1. Server page → **Share server** `MODAL`: email, designation, and **which permissions** this person gets on this server (at least one) → **Invite** → `TOAST`. - ✖ "This server has already been shared with this user." · "This user is already a member of the organization." 2. The person accepts the invite (same page as Flow E) → the server appears in their **Servers → Shared with me** tab (U13.1). 3. Shared people are listed apart from members, can change only what was given, and never see create / delete / share for that server. **Edit permissions** `MODAL`. **Remove** → `CONFIRM`. --- ## U4. Account (user menu) **Status:** Backend Phase 3 (account) — requirements complete **Purpose:** A logged-in user manages their account information, security and 2FA, password, IP whitelist, login history, activity and settings. Notifications is a separate user-menu section (U5). **Opens from:** User menu (top right). **Build:** 🟢 READY — backend Phase 3 covers these screens **Depends on:** Sign up & login (U2). Backend Phase 3. **Permissions:** Each person manages their own account. **Open questions:** #12 #### Screens | Screen | What's on it | Type | |---|---|---| | Account | Tabs: Account information · Security & 2FA · Update password · IP whitelist · Login history · Activity log · Settings | `PAGE` | #### Flows **User menu** (top right) → pages in this order: **Account** → Notifications. Notifications is at account level but **not inside the Account page** — see U5. **Account** is one `PAGE` with tabs in this order: Account information → Security & 2FA → Update password → IP whitelist → Login history → Activity log → Settings. ### Account information (U4.1–U4.3) 1. **User menu → Account** → **Account information** tab: name, email, details, my organizations (U4.1). 2. Edit details → **Save** → `TOAST` "Profile updated" (U4.2). 3. **Change email** `MODAL` (U4.3): new email + password → **Send link** → `TOAST` "Check your new email". The email changes only after the link in that email is opened → **Email changed** `PAGE`. ### Security & 2FA (U4.8, U4.9, U4.16) 1. **Account → Security & 2FA** tab. 2. **Email 2FA** switch (U4.8) → on: `TOAST`. Off: `MODAL` password → `TOAST`. - **Backup codes** `MODAL`: shown **once** — view and **download** (B11.21). They are **never emailed**; the email only says codes were generated, so the dialog says "save these now". - **New codes** → `CONFIRM` "Old codes stop working". 3. **Google Authenticator** (U4.9) → **Set up** `MODAL`: scan QR → enter code → **Turn on** → `TOAST`. Turn off → `MODAL` password. 4. **Sessions** (U4.16): Log out one → `CONFIRM`. Log out all others → `CONFIRM`. ### Update password (U4.4) 1. **Account → Update password** tab (or **Change password** `MODAL`): current, new, confirm → **Save** → `TOAST` "Password changed. Other devices were logged out." ### IP whitelist (U4.10) 1. **Account → IP whitelist** tab: switch + list. 2. **Add IP** `MODAL` → `TOAST`. Delete → `CONFIRM`. 3. While the switch is on, logging in from an address that isn't on the list asks for email approval first (Flow B step 2, v7). ### Login history (U4.11) 1. **Account → Login history** tab: table of sign-ins. ### Activity log (U4.12) 1. **Account → Activity log** tab: list of account activity. - The organization-wide log is the **Audit log** (U17). ### Settings (U4.5–U4.7) 1. **Account → Settings** tab. 2. **Email preferences** (U4.5): 3 switches → `TOAST` on each change. 3. **Delete protection** switch (U4.6) → `TOAST`. 4. **Delete account** `MODAL` (U4.7): password + reason (optional) → **Delete account** → `CONFIRM`. - ✖ Blocked with the reason: "Please pay negative balance first." · "Please delete servers before deleting account." - ✔ Account deleted → logged out → **Log in** page with `TOAST`. --- ## U5. Notifications (user menu) **Status:** Backend Phase 3 (U4.14, U4.15, U4.17) + Phase 11 — requirements complete **Purpose:** See notifications in the bell, and set up channels for **server and app events**. Account, billing and plan notifications are sent **by email** (as v7) — at account level, from the user menu (not inside the Account page). **Opens from:** Bell (top bar); User menu → Notifications. **Build:** 🟢 READY — backend Phases 3 and 11 cover these screens. NEEDS YOUR DECISION: where the per-server Notifications screen goes (U13.4 order is fixed) **Depends on:** Account (U4). Backend Phases 3 and 9. **Permissions:** Each person manages their own notifications. #### Screens | Screen | What's on it | Type | |---|---|---| | Notifications | Bell list + notification channels | `PAGE` | | Add channel | Channel type and its fields | `MODAL` | #### Flows ### Flow — Notifications (U4.14, U4.15, U4.17, B11.7–B11.10) Covered below: Bell and notification list · Channels page · Add a channel · Test, edit or delete a channel · Account notifications · Server notifications · Server and app events · Unsubscribe link. ### Notifications — Bell and notification list (U4.14) **Bell** → dropdown → **View all** → Notifications `PAGE` (U4.14). Click one → the page it's about. An **announcement** (B11.17) has nothing to open, so it shows as a plain message. ### Notifications — Channels page (U4.15) **User menu → Notifications** → channels list (U4.15). ### Notifications — Add a channel **Add channel** `MODAL`: pick type — **Email, Telegram, Slack, Discord, Pushover, Webhook** → its fields → **Save** → `TOAST`. Edit `MODAL` the same way. ### Notifications — Test, edit or delete a channel **Send test** → `TOAST` "Test sent". **Delete** → `CONFIRM`. - ✖ A channel that keeps failing (B11.9) shows **"not working"** with the last error → **Send test** to check it again. ### Notifications — Account notifications **Email is the primary way** account notifications are sent, as in v7 (Bhavik, 2026-10-07). - Account, security, billing, plan and organization notifications go **by email only** (and the bell). They are **not** sent to Slack, Telegram, Discord, Pushover or webhooks — there is no channel picker for them. - Below the channels a short note says: "Account, billing and plan messages are sent to your email." - Security and billing emails are always sent (B11.5) — e.g. **password changed**, **new login from a new device or IP**. Other informative emails can be turned off in **Email preferences** (U4.5). - The **extra channels** (Telegram, Slack, Discord, Pushover, Webhook) are for **server and app events** only, as in v7 (next flow). - **Emails:** only the existing V8 email flows are used (sign-up, verification, password reset, invite, new-IP approval, 2FA code, billing/plan and server alerts). The newly proposed extra emails (account deleted, logged out of all devices, plan changed, plan price / feature change) are **not** added. ### Notifications — Server notifications (B11.7): set on **each server**, not here. - On the server: **attach a channel**, then tick its **event groups** — Alerts · Backups · Apps & deploys · SSL & domains · Databases · Server changes. - **All six are on by default**, so the screen is for **turning things off**: "you get everything; untick what you don't want." - Unticking **Alerts** silences that server's CPU, memory, disk, load, service and reachability warnings — the screen says so. - ⚠ Where this screen sits in the server menu is **not decided yet** (the menu order in U13.4 is fixed and has no Notifications item). The per-server **alert limits** (U13.4 item 12) have the same question. ### Notifications — Server and app events (B11.11, B11.12): - They cover actions done in **Central** and problems found on the server — backups, SSL, auto-deploys, metrics, services and reachability. Work done **directly in the server's own panel is not notified** (that panel shows it), so this is not a full history of the server. - So each notification says where it came from. - **Alerts** (CPU, memory, disk, load, service down, server unreachable) arrive **once** until fixed, then a **"back to normal"** message (B11.14). - An alert also lists the server's **top processes** (B11.13). ### Notifications — Unsubscribe link (U4.5) Informative emails have an **unsubscribe link** (B11.10) → opens **Email preferences** (U4.5). --- ## U6. Members **Status:** Backend Phase 4 (Pair 1) — requirements complete **Purpose:** Owners and admins invite people, give them one role, and remove them. **Opens from:** Sidebar → Members. **Build:** 🟢 READY — backend Phase 4 complete **Depends on:** Organizations (U3); Plans (U8) — the team works under the owner's plan. Backend Phase 4. **Permissions:** One role per member. The owner's row has no actions. #### Screens | Screen | What's on it | Type | |---|---|---| | Members | Cards, members table, pending invites | `PAGE` | | Add member | Email, designation, role | `MODAL` | #### Screen states - **Members** — owner row has no actions (B4.4) · my own row → **Leave organization** · empty → "No members yet" + **Add member**. - **Add member** — "This user is already in the organization." #### Flows ### Flow — Invite and manage (U6.1–U6.5, B4.3–B4.4) 1. Sidebar → **Members** `PAGE` (U6.1): cards (total, pending, owners), filter, sort, search. 2. **Add member** `MODAL` (U6.4): email + designation + **one role** (Admin, Member or custom) → **Send invite** → `TOAST` "Invitation sent". - ✖ "This user is already in the organization." 3. Invite shows under **Pending invites** (U6.3): email, role, "expires in N days" (7 days). **Resend** `TOAST`. **Cancel** `CONFIRM`. 4. The person accepts (Flow E) → moves to the **Members** table (U6.2). 5. Members table: name, email, designation, role, joined. **Change role** `CONFIRM`. **Remove** `CONFIRM`. 6. One role per member (U6.5). The owner's row has no actions. **Leave organization** → `CONFIRM` in your own row → your default organization. --- ## U7. Roles **Status:** Backend Phase 4 (Pair 1) — requirements complete **Purpose:** Owners and admins decide what each role can view or manage. **Opens from:** Sidebar → Roles. **Build:** 🟡 WAITING ON BACKEND — the permission list is "a separate step" in backend Phase 4, so the permissions to tick are not published yet **Depends on:** Organizations (U3). Backend Phase 4 — the permission list is not published yet. **Permissions:** Owner and Admin are fixed roles and can't be edited. **Open questions:** #8 #### Screens | Screen | What's on it | Type | |---|---|---| | Roles | Cards, role list | `PAGE` | | Create / edit role | Name, description, View / Manage permissions | `MODAL` | #### Screen states - **Roles** — Delete off while the role has members — "3 members use this role — move them first" (B4.5). #### Flows ### Flow — Roles (U7.1–U7.5) 1. Sidebar → **Roles** `PAGE` (U7.1): cards (total, system, custom, in use), role cards. 2. System roles (Owner, Admin): view only `MODAL` (U7.2). 3. **Create role** `MODAL` (large) (U7.3): name, description → tick permissions **View** / **Manage** per item (ticking one ticks its parent, U7.5) → **Save** → `TOAST`. 4. Edit → same pop-up. 5. **Delete** → `CONFIRM` (U7.4). Blocked while members use it — shows how many and "move them first". --- ## U8. Plans & subscription **Status:** Backend Phase 7 — requirements complete **Purpose:** The owner sees their plan and usage, changes or cancels it, and redeems codes. **Opens from:** Sidebar → Plans. **Build:** 🟢 READY — backend Phase 7 complete. Open: D-33, D-34 **Depends on:** Billing (U9) — plans are paid from credit. Backend Phase 7. **Permissions:** One plan per owner. Members see the limits, not a buy button. **Open questions:** #5, #6, #13, #14, #15 #### Screens | Screen | What's on it | Type | |---|---|---| | Plans | Current plan + plan cards | `PAGE` | | Change plan | Price, credit back, coupon, confirm | `CONFIRM` | | Cancel plan | End date, what you lose, reason | `MODAL` | | Redeem code | Code → what it gives → confirm | `MODAL` | | Locked account | Add credit → pay plan | `PAGE` | | Pay | Summary, coupon, wallet, add credit | `MODAL` | | Upgrade | Shown when a plan limit is reached | `MODAL` | #### Screen states - **Plans** — status pill active / expired / locked (B7.25) · days left always next to the **real date** · downgrade blocked → the card shows what to remove first instead of the button (B7.8) · migrated restructured user → only **Managed** and **Self Managed** cards (B7.14). - **Change plan** — not enough credit → "Add $X credit first" + **Add credit** (B7.7). - **Cancel plan** — after cancelling → banner "Your plan ends on 12 Nov 2026" + **Resume** (B7.9). - **Pay** — wallet covers it → button becomes **Confirm & pay** · see U8.9. - **Upgrade (limit reached)** — member → no buttons, "Ask the organization owner to upgrade" (U8.11) · feature not in the plan → "Upgrade your plan to use this" (B7 intro). - **Redeem code** — unknown · already used · expired · switched off · not for this account (B7.23). - **Locked account** — unlocks by itself after credit + plan payment (B7.22) · member → same page naming the owner, no buttons. #### Flows **Plans are created by the admin** (Admin plans, A4) and shown to users on `/plans`. The screen shows whatever the backend sends. **One plan per owner** (B7.3), covering all organizations they own. Members see the limits, not a buy button. ### Flow — Plans page (U8.1–U8.7) Covered below: Current plan · Plan list · Change plan · Cancel plan · Lifetime · Banners · Expiry · Locked account · Special current plans · Enterprise · Redeem a code. ### Plans — Current plan (U8.1) Sidebar → **Plans** `PAGE`. Top: **current plan** (U8.1) — name, status (active / expired / locked), usage bars, the **exact renewal date** and cost. "N days left" sits next to the date, never instead of it (B7.25). ### Plans — Plan list (U8.2) Below: **plans** (U8.2) — period switch, cards or compare table, in the admin's order. - **Everyone sees the same plans** (B7.14). - Only a migrated "restructured" user sees their own two (**Managed**, **Self Managed**) — so the list is always read for the signed-in account. ### Plans — Change plan (U8.3) **Choose this plan** → **Change plan** `CONFIRM` (U8.3): price, tax, unused days returned as credit (B7.7), credit used, amount due, new end date, **coupon code** (B7.13) → **Confirm** → `TOAST` → current plan updates. - ✖ Not enough credit → "Add $X credit first" → **Pay** (U8.9). - ✖ **Downgrade blocked** (B7.8): - The card shows why instead of a button, and **what to remove first** — for example "Remove 2 servers first", "Remove other members first", a feature in use, or **an add-on the new plan doesn't include** (B7.26) — each with a link. - Some plans are **no downgrade**. ### Plans — Cancel plan (U8.4) `MODAL` (large) (U8.4): end date, what you lose, reason → **Keep plan** or **Cancel plan** `CONFIRM` → `TOAST` → banner "Your plan ends on " + **Resume**. ### Plans — Lifetime (U8.5) (U8.5): only if the admin made offers. **Buy** → same pop-up as step 3. New users who come from the lifetime deal link follow **Flow H** (U2). ### Plans — Banners (U8.6) (U8.6): trial days left, renews soon with low credit, cancelled (Resume `CONFIRM`), expired (Renew), payment failed (Add credit). - **Price changed** (B7.17): current-plan card shows the new price for the next renewal (old one struck through) and the date. Nothing charged today. - **Features or limits changed** (B7.18): note "From : 25 servers instead of 50." Already over → link to what to remove. - **Trial ended** (B7.6) → **Choose plan** `PAGE`. ### Plans — Expiry (B7.12): banner countdown to the dates the backend sends — a **warning date**, then a **lock date**. What happens depends on the server, so the banner **names them**: - **Managed servers:** powered off at the provider on the warning date, then **deleted at the provider** on the lock date. - **Self-managed servers:** only **removed from Central** on the lock date; they keep running at the provider. - The account (and the owner's team) is locked on the lock date. The banner always shows the **date**, never a number of days: the admin can change those days (B7.10–B7.12). - While expired, every server action is off with **"Plan has expired. Please renew it"**. Still allowed: **view everything**, **delete a server**, **add credit / renew**. Pages stay readable — only the buttons are off. - **Add credit** is enough (B7.10): the plan renews **by itself** as soon as there is enough, any day up to the lock date. The banner says that, so nobody waits for a Renew button. ### Plans — Locked account `PAGE` (B7.12): - Only billing is reachable. - ✔ **Add credit** → **Pay plan** → unlocks by itself (B7.22). - Nothing comes back on its own: - **self-managed** servers are still at the provider → reconnected from **Add server → Connect a panel**; - **managed** servers were deleted there and are gone. - The page says which — never one blanket "your servers are safe". - Member → same page naming the owner, no billing. ### Plans — Special current plans Special current plans: **own plan from the admin** (B7.20, may not match any card), **Free forever** (B7.21, no renewal), **archived plan** (B7.19, kept until they move; step 3 warns they can't come back). ### Plans — Enterprise (B7.15): "Need something bigger?" → contact form `MODAL` → `TOAST` "We'll get back to you". ### Plans — Redeem a code (U8.7) (U8.7, from B7.23): - **Redeem code** `MODAL` → paste the code → shows **what it gives** (plan or credit) → **Confirm** `CONFIRM` → `TOAST`. - ✔ Plan code → stays on Plans with the new plan. Credit code → **Billing → Wallet**. - ✖ unknown · already used · expired · switched off · not for this account. - The same pop-up opens from the Wallet tab. ### Flow — Trial and Free plan (U8.8) 1. **Trial starts by itself** at sign-up (B7.6) — no screen. The admin sets how many days. 2. Banner on **Plans** and the Dashboard: "Trial — N days left (ends )" (U8.6). 3. **Trial ended** → **Choose plan** `PAGE`: the user must pick a **paid** plan to continue (B7.6) → **Pay** (U8.9). Whether the **Free** plan may be picked after a trial is open question 5. 4. **Free** plan card ($0) → **Choose this plan** → `CONFIRM` → `TOAST` → **Dashboard**. ### Flow — Pay (U8.9) 1. **Summary** `MODAL`: plan, period, price, tax, **coupon code**, credit used, amount due. 2. Wallet covers it → **Confirm & pay** → `CONFIRM` → `TOAST` "Plan active" → **Dashboard**. 3. Wallet too low → **Add credit** (amount filled with what's missing) → saved card, new card or other method → payment page. 4. Back to Central → "Confirming payment…" → ✔ `TOAST` → plan active → **Dashboard**. ✖ Failed → message + **Try again**. Still processing → "We'll notify you when it's done." ### Flow — Limit reached (U8.10) 1. User tries something over the plan limit (for example Add server) → stopped → **Upgrade** `MODAL`: current limit + plans with a higher limit → **Pay** (U8.9) → back to what they were doing. ### Who can pay (U8.11) - Owners and people with Billing access see the pay buttons. - Members are **locked with the owner** (B7.12) and get the day −7 warning first. --- ## U9. Billing **Status:** Backend Phase 6 (Pair 1) — requirements complete **Purpose:** The owner adds credit, sees every payment and charge, sees how existing **managed servers** are paid (Managed plan), and manages cards and auto recharge. **Opens from:** Sidebar → Billing. **Build:** 🟢 READY — backend Phase 6 complete **Depends on:** Sign up & login (U2), Organizations (U3) — billing belongs to the owner. Backend Phase 6. **Permissions:** The account owner and anyone a role gives billing access to (U9.8). **Open questions:** #4, #7, #13 #### Screens | Screen | What's on it | Type | |---|---|---| | Billing | Tabs: Overview, Wallet, Transactions, Usage, Managed plan, Auto recharge, Cards, Billing profile | `PAGE` | | Add credit | Amount, coupon, payment method | `MODAL` | #### Screen states - **Add credit** — no method on → "Payments are temporarily unavailable" · back from the gateway → "Confirming payment…" · credit is added **only after the gateway confirms** (B6.4) · failed → **Try again**. - **Billing — Transactions** — empty → "No transactions yet" + **Add credit**. - **Billing — Auto recharge** — no card → switch off with "Add a card first" → **Cards**. - **Billing — Managed plan** — no managed servers → tab not shown · credit run out → banner with the due / expire / deletion dates + **Add credit** (B6.12). #### Flows Sidebar → **Billing** `PAGE`. Tabs in this order. All amounts, limits and dates come from the backend. ### Flow — Billing tabs (U9.1–U9.7) Pages in this order: Overview · Wallet · Add credit · Transactions · Usage · Managed plan · Auto recharge · Cards · Billing profile. ### Billing — Overview (U9.1) (U9.1): next charge, wallet balance, this month, usage, recent activity, any unpaid-credit banner. ### Billing — Wallet (U9.2) (U9.2, from B6.3): **paid**, **free**, **promo** balances + total; promo rows show expiry. Trend and activity. **Redeem code** `MODAL` (U8.7). ### Billing — Add credit `MODAL` (B6.4): 1. Amount. ✖ "Minimum is $N" · "Maximum is $4,000 per payment". 2. **Coupon code** (off with the reason at or below the minimum). 3. Base, tax, discount → total. 4. **Payment method** — only the ones turned on (B6.1). None → "Payments are temporarily unavailable". 5. **Pay** → payment page → back to Central → "Confirming payment…" → ✔ `TOAST` "Credit added" → **Wallet**. ✖ Failed → **Try again**. Waiting → "We'll notify you when it's done." ### Billing — Transactions (U9.3) (U9.3, from B6.7): payments and charges, filters, search, Export. **Receipt** on payment rows. ### Billing — Usage (U9.4) (U9.4, from B6.11): managed servers — hours this month, amount so far, last charged. Full details per server are on **Managed plan** (U9.9). ### Billing — Managed plan (U9.9) `/billing/managed` (from B6.8–B6.13). How the account's **managed servers** are paid — **hourly from paid credits**. Users **can't create new managed servers** (Bhavik, 2026-10-05), so this tab is for **existing** managed servers only; it is **shown only when the account has at least one managed server** (new users never see it). 1. **Summary** at the top: number of managed servers · total monthly price · charged so far this month · **paid credit** balance (only paid credit pays for managed servers, B6.10) → **Add credit** (U9.3). 2. **Managed servers** table: | Column | Shows | |---|---| | **Server** | Name — click → **Server page** (U13.3) | | **Provider · region · size** | DigitalOcean, Vultr, Linode or Hetzner, with region and size (B6.8) | | **Monthly price** | The price saved with the server when it was created (B6.9) | | **Hourly rate** | Monthly price ÷ (days in this month × 24) (B6.10) | | **Hours this month** · **Charged so far** · **Last charged** | From usage (B6.11) | | **Status** | Running · Powered off (unpaid credit) · Will be deleted on \ | 3. **Credit run out** (B6.12) — when paid credit is 0 or below, a banner shows the account's own dates: reminders until the **due date**, then on the **expire date** servers with **no apps and no databases are deleted** and the others **powered off**, then the rest are **deleted** on the **deletion date**. Each row says which of the two will happen to it. **Add credit** stops the process (B6.13). 4. **Back to positive** (B6.13): the dates go away; powered-off servers **stay off** until started again from their server page. 5. A migrated "restructured" v7 user also sees their **Managed** plan here, read-only, next to the servers it covers (B7.14). 6. Not here: the managed-server **price list** (admin, A4/admin settings) and creating managed servers (not for users). ### Billing — Auto recharge (U9.5) (U9.5, from B6.5–B6.6): - Switch, low-balance limit, amount → **Save** `TOAST`. - ✖ No card → switch blocked "Add a card first" → **Cards**. - Shows the last automatic charge + its result. - **Remind me when credit drops below** ($1–$1,000, warning only). ### Billing — Cards (U9.6) (U9.6): list. **Add card** `MODAL` → `TOAST`. Set default `TOAST`. Remove `CONFIRM` (warns if auto recharge uses it). ### Billing — Billing profile (U9.7) (U9.7, from B6.2): name, company, email, address, country, tax number + receipt preview → **Save** `TOAST`. Saved receipts don't change. ### U9.8 Who sees Billing - The account owner and anyone a role gives billing access to. Everyone else sees "Ask the organization owner to add credit" and no pay button. --- ## U10. Dashboard **Status:** Not in the backend doc yet · Flow: ServerAvatar v7 **Purpose:** The first screen after login: health of everything, money at a glance, and the next step for new users. **Opens from:** Sidebar → Dashboard; default landing page. **Build:** 🟡 WAITING ON BACKEND — no backend phase for dashboard data yet **Depends on:** Sign up & login (U2) — the Dashboard opens after sign-up and login; shows data from Servers (U13). No backend phase yet. **Open questions:** #11 #### Screens | Screen | What's on it | Type | |---|---|---| | Dashboard | Getting started, cards, server status, wallet, recent activity | `PAGE` | #### Flows First screen after login. `PAGE` 1. **Getting started** (new organizations, v7): three steps — **Add server** → **Create application** → **Install SSL**. Each step links to its screen and ticks itself off. **Skip** hides it; it also hides itself when all three are done. - Under the steps, small counters as in v7: **Servers · Applications · SSL sites · Databases · System users** (v7 onboarding counts). The three steps stay the same; the counters only show progress. 2. Cards: servers, sites, members, plan usage. 3. Server status list (online / offline, CPU, memory) → click a server → **Server page** (U13.3). 4. Wallet balance and this month's spend → **Billing** (U9). 5. Recent activity → **Audit log** (U17). 6. No servers yet → "Add your first server" → **Add server** (U13.2). 7. **Only the current organization is counted.** Servers shared with me from other organizations are **not** in these cards or lists — they are under **Servers → Shared with me** (U13.1). Cards and blocks the user's role can't view are hidden (U1.6). --- ## U11. Integrations **Status:** Backend Phase 5 — requirements complete **Purpose:** Organization-level page: connect the cloud provider accounts used to create servers and the Git accounts used to deploy sites, and see every account with "Used on" (B5.14). **Opens from:** Sidebar → Integrations (organization level); also from the Add-server wizard. **Build:** 🟢 READY — backend Phase 5 describes it **Depends on:** Organizations (U3) — cloud providers belong to the organization. Backend Phase 5. **Permissions:** Buttons follow the user's organization role. **Open questions:** #9 #### Screens | Screen | What's on it | Type | |---|---|---| | Integrations | Tabs: Cloud providers · Git accounts | `PAGE` | | Connect provider | Provider, name, API token or access key + secret | `MODAL` | | Connect Git | Name, GitHub / GitLab / Bitbucket, token, servers | `MODAL` | #### Flows **Sidebar → Integrations** `PAGE` (also opens from the Add-server wizard). Tabs: **Cloud providers** → **Git accounts**. Buttons follow the user's **organization role**. - **Cloud providers belong to the organization** chosen in the switcher, not to the person who connected them. They stay when that person leaves. Title: "Cloud providers for ". ### Cloud providers (U4.I1) 1. List: provider, account name, servers created with it, status. 2. **Connect provider** `MODAL`: - Pick provider → type a **name** (several accounts per provider allowed). - **API token** for Vultr, DigitalOcean, Linode, Hetzner. - **Access key + secret key** for AWS Lightsail. - A help line says where to create it. 3. **Save** → token checked → ✔ `TOAST`, back to the list. ✖ "The provider rejected this token" under the field. 4. **Edit** `MODAL`: rename or paste a new token (blank keeps the current one). 5. Provider rejects the token later → row shows **Needs new token** → **Edit**. New servers can't use this account until then. 6. **Disconnect** → `CONFIRM`. Blocked while servers were made with it: button off, "Used by N servers" with the list. - Existing ServerAvatar users: Vultr, Hetzner and Lightsail come across ready. **DigitalOcean and Linode** arrive as **Needs new token**, with one line saying why. ### Git accounts (U4.I2–U4.I4) 1. List: provider, account name, "Used on: server 1, server 2", last test. 2. **Connect Git** `MODAL` → **name** + GitHub / GitLab (incl. self-hosted URL) / Bitbucket + token → pick **servers / all servers** → **Connect**. 3. Result per server: done, or offline → **Retry**. 4. **Test** per server → `TOAST` works / the error. 5. Accounts found on a server's panel show in the same list, marked **found on this server** — **once**, even when each server has its own token. Add to more servers → paste the token again `MODAL` (U4.I3). 6. **Replace token** `MODAL` (U4.I4): lists the servers it will overwrite (untick any) → result per server. 7. **Remove** → `CONFIRM` (U4.I4): **one server** / **all servers** → result per server. Tokens are never shown again. --- ## U12. Backup Storage **Status:** Backend Phase 5 — requirements complete **Purpose:** Connect the storage that server and app backups are saved to, and see **all backups** of the organization in one list (`/backups`, v7) — at organization level, from the sidebar. **Opens from:** Sidebar → Backup Storage; also from server and app Backups when no storage exists yet. **Build:** 🟢 READY — backend Phase 5 describes it **Depends on:** Organizations (U3). Backend Phase 5. **Permissions:** Buttons follow the user's organization role. #### Screens | Screen | What's on it | Type | |---|---|---| | Backup Storage | Storage list, test, edit, replace keys, remove | `PAGE` | | Add storage | Type, fields for that type, name, servers | `MODAL` | | Backups (`/backups`) | All backups across this organization's servers and apps — filters, download, restore, delete | `PAGE` | #### Flows ### Flow — Backup storage (U4.B1–U4.B6) **Sidebar → Backup Storage** `PAGE` (also opens from server and app Backups when no storage exists yet; after saving, the user goes back there). Covered below: Storage list · Add storage · Fields for each type · Pick servers · Test · Edit or replace keys · Storage found on a server · Remove. - Every action appears in the organization **Audit log** (U17) — never the keys. ### Backup storage — Storage list (U4.B1) List (U4.B1): name, type, bucket / folder, "Used on: …", last test. Empty → "No storage connected yet" + **Add storage**. ### Backup storage — Add storage (U4.B2) `MODAL` (U4.B2) → pick type: Amazon S3, Cloudflare R2, Backblaze B2, Wasabi, DigitalOcean Spaces, other S3-compatible, Google Drive (service account file), FTP, SFTP. ### Backup storage — Fields for each type Fields for that type: - S3 types → bucket, region, endpoint, access key, secret key, folder. - FTP → host, port, username, password, folder, TLS, passive mode. - SFTP → host, port, username, password or private key (+ passphrase), folder. - Google Drive → service account JSON, shared drive folder ID. ### Backup storage — Pick servers **Name** → pick **servers / all servers** → **Save** → connection tested → result per server (works, failed, offline → Retry) → `TOAST`. ### Backup storage — Test (U4.B3) on a row (U4.B3) → `TOAST` "Connection works" or the error. ### Backup storage — Edit or replace keys (U4.B4) **Edit** `MODAL`. **Replace keys** `MODAL` (U4.B4): lists the servers it will overwrite (untick any) → result per server. ### Backup storage — Storage found on a server (U4.B5) Storage found on a server's panel → marked **found on this server**, shown once. Add to more servers → paste the keys again `MODAL` (U4.B5). ### Backup storage — Remove (U4.B6) → `CONFIRM` (U4.B6): **one server** / **all servers** → result per server. ### Flow — Backups page (organization-wide, v7) 1. Sidebar → **Backups** `PAGE` (`/backups`): every backup of this organization's servers and apps, newest first. - Columns: Backup (server or app name) · Server · Type (files / database / full) · Storage · Size · Date · Status · Actions. - Filters: server · type · storage · date; search by name. 2. Actions (each follows the role, U1.6): - **Download** → file download (or "Preparing…" then download). - **Restore** → `CONFIRM` with the "What will happen" box → progress → `TOAST`. - **Delete** → `CONFIRM` (also several at once). - **Archive** tab: older backups kept in storage (v7 "Archive backups"). 3. Set up or change a schedule → opens that server's or app's **Backups** page (U13.4 / U14.4). This page only lists. 4. No storage yet → empty state "Connect backup storage first" → **Backup Storage**. No backups yet → "No backups yet" + **Go to servers**. 5. **Not in V8:** backups of **deleted servers** and **restore to another server** (v7 has them; Bhavik, 2026-10-07). Restore puts a backup back on its own server only. --- ## U13. Servers **Status:** Backend **Phase 8** (create & connect, B8.1–B8.12) — requirements complete **Purpose:** Users add servers (cloud, own, existing panel) and manage each one from its server menu. **Opens from:** Sidebar → Servers. **Build:** 🟡 WAITING ON BACKEND — adding a server is written (B8.1–B8.12); server panel features are not taken into this doc yet. How server data refreshes is open (backend Q3) **Depends on:** Integrations (U11) for cloud servers, Plans (U8) for the server limit, a verified email (U2). **Permissions:** Server menu items the user isn't allowed to see are hidden. There is **no Transfer server** for users — only ServerAvatar admins transfer servers (A8). **Open questions:** #1, #7, #10, #12 #### Screens | Screen | What's on it | Type | |---|---|---| | Servers | Tabs **Servers** · **Shared with me**; cards, search, sort | `PAGE` | | Add server | Wizard: way → details → review → progress | `PAGE` | | Server page | Server menu with 16 items | `PAGE` | | Connect your accounts here too? | Add Git / storage to the new server | `MODAL` | #### Server creation flowchart Everything that happens when a user adds a server, taken from the steps in **Flow — Add a server** (U13.2) Users **can't create managed servers** (Bhavik, 2026-10-05), so there are three ways. **What's included in each way** | Way | Who provides the server | What the user enters | What Central does | |---|---|---|---| | **Cloud provider** | The user's own cloud account, connected in Integrations (U11) or inside the wizard | Provider account, region, size, Ubuntu version, stack, name, optional SSH key (root password for Linode) | Creates the server at the provider and installs the panel | | **My own server** (custom server) | The user's own machine | Name, stack, then root password **yes**: IP, SSH port, root password · **no**: copy and run a one-line command | Installs the panel (yes) or waits for the command, then **Verify** (no) | | **Connect a panel** | A server that already runs the panel | Name + panel address + Central key | **Validate** → **Connect** | - Checks for every way: the email must be **verified** first; the plan's **server limit** is checked at **Review → Create** (✖ → Upgrade, U8.10). - Database engines are **not** picked here — they are installed later on the server's own panel. **1. Start: Add server** ```flow Servers page or top bar | Add server Email verified? | ✖ no → "Please verify your email address." — wizard blocked Choose a way | step 1 of the wizard → Cloud provider: see chart 3 (needs a provider, chart 2) | → My own server: see chart 4 | → Connect a panel: see chart 5 ``` **2. Add a cloud provider** (Integrations, U11) ```flow Sidebar → Integrations → Cloud providers | or "Connect provider" inside the wizard, without leaving it Connect provider (pop-up) | pick provider → type a name (several accounts per provider allowed) Paste credentials | API token: Vultr, DigitalOcean, Linode, Hetzner · access key + secret key: AWS Lightsail Save → token checked → ✔ Accepted: account in the list — ready to use in the wizard | → ✖ Rejected: "The provider rejected this token" under the field Later, token stops working | row shows "Needs new token" → Edit — new servers can't use it until fixed ``` **3. Create a server on a cloud provider** ```flow Choose a way → Cloud provider Provider account | from Integrations — none yet → Connect provider (chart 2) Server details | region, size, Ubuntu version, stack, name, optional SSH key (root password for Linode) Review → Create | ✖ plan limit reached → Upgrade (U8.10) Progress page | Creating → Installing → Ready / Failed — safe to leave and come back → ✔ Ready: next step | → ✖ Failed: reason + Retry · Delete at provider Connect your accounts here too? | add Git / storage to the new server, or Skip Server page | server menu (U13.4) ``` **4. Create a custom server (My own server)** ```flow Choose a way → My own server Server details | name, stack Do you have the root password? → Yes: enter IP, SSH port, root password — Central installs the panel | → No: copy a one-line command → run it on the server as root → Verify Review → Create | ✖ plan limit reached → Upgrade (U8.10) Progress page | → Ready / Failed (Retry) Connect your accounts here too? | add Git / storage, or Skip Server page | server menu (U13.4) ``` **5. Connect a server that already runs the panel** ```flow Dashboard Servers Add server Name + panel address + Central key Validate Connect Server Details ``` - The new panel's address and login link are **never shown until Central has claimed the panel** (U13.2a). #### Flows ### Flow — Server list (U13.1) 1. Sidebar → **Servers** `PAGE`: cards (total, healthy, warning, offline), search, sort, server cards with "last seen". - Each card says how it is paid: **plan** or **Managed** (B6.8, with the monthly price). - **Powered off for unpaid credit** (B6.12): says so, with the deletion date and **Add credit** — not "offline". Credit added → the deletion date goes, the server **stays off** until started again (B6.13). - Before that date, managed servers that will be **deleted** (no apps and no databases) are marked apart from those that will only be **powered off** (B6.12). 2. Click a server → **Server page** (U13.3). **Add server** → wizard (U13.2). 3. **Tags** (U25): filter by tag, "Recently viewed" row. 4. **Shared with me** tab (`/servers/shared`, v7 shared servers, B4.6): servers **other organizations shared with me**, one by one — server name, IP, **from organization**, **shared by**, application count. - Open → **Server page** with only the **menu items and buttons for the permissions given** for that server (view → read-only, manage → can change). No create / delete / share, ever. - Opening a shared server doesn't change my current organization. - Each card has a **Shared** badge and "from "; the tab name shows the count ("Shared with me · 3"). - **Filter** by organization and search by name or IP. - Empty → "No server is shared with you yet." ### Flow — Add a server (U13.2, wizard `PAGE`) Email not verified → wizard is blocked with "Please verify your email address." **Users can't create managed servers** — there is no "Managed server" choice in this wizard (Bhavik, 2026-10-05). ⚠ Differs from backend **B6.9** and now **B8.2**, which both describe users creating them. **Stack** (B8.7): LEMP, LAMP, OpenLiteSpeed or MERN. **No database engine here** — it is installed on the panel afterwards, and the review step says so in one line. ⚠ **ServerAvatar Lite** (B8.6), the free managed server, has **no screen in Central** — it is installed by a script with no ServerAvatar account, so it never reaches this wizard. - ⚠️ **Backend decision required** — backend B6.9 still lets users create managed servers; this doc follows Bhavik's decision. Update when the backend doc changes. 1. **Add server** → **Choose a way:** Cloud provider · My own server · Connect a panel. 2. **Fill in details:** - **Cloud provider:** provider account (connected ones), region, size, Ubuntu version, stack, name, optional SSH key (root password for Linode). No account yet → **Connect provider** `MODAL` without leaving the wizard. - **My own server:** name, stack → **"Do you have the root password?"** - **Yes** → IP, SSH port, root password → Central installs the panel for the user. - **No** → **Copy command** (one line to run on the server as root) → run it → **Verify**. - **Connect a panel:** name + panel address + Central key → **Validate** → **Connect** → **Server Details**. - Database engines are not picked here — they are installed later on the server's own panel. 3. **Review** → **Create**. - ✖ Plan limit reached → **Upgrade** (U8.10). 4. **Progress** `PAGE` (U13.2a): **Creating → Installing → Ready / Failed**. Safe to leave and come back. The new panel's address and login link are **never shown until Central has claimed the panel**. - ✖ Failed → reason + **Retry** · **Delete at provider** `CONFIRM`. 5. ✔ Ready → **Connect your accounts here too?** `MODAL` (U13.2b): add Git / storage accounts to the new server, or **Skip** → **Server page** (U13.3). ### Flow — Server page (U13.3) 1. **Server page** `PAGE` with a **server menu** on the left (U13.4). Items the user isn't allowed to see are hidden. On phones → **"Jump to"** dropdown at the top (same for the app menu). 2. Server offline or key not working (U13.5) → banner + **Retry**. **Reconnect** `MODAL` (new key). 3. **Rename** `MODAL` (U13.6) → `TOAST`. 4. **Disconnect** → `TYPE-TO-CONFIRM` (server name): removes it from Central only, the server keeps running → **Server list**. 5. **Delete server** → `TYPE-TO-CONFIRM` (cloud and managed servers): server name + tick **"Also delete it at "** → **Server list** `TOAST`. Not ticked → same as Disconnect. 6. **Managed server** (U13.7, existing ones only — users can't create new ones). **The OSS panel is not accessible** to the user on a managed server: no "open panel" link, no panel address or login shown — everything is done from Central's server menu (Bhavik, 2026-10-07). hours used this month, amount so far, last charged + link to **Billing → Usage**. Deleting it stops the hourly charges. 7. **Managed server, credit run out** (B6.12): - Banner with the server's own dates: **powered off on \**, then **deleted on \**. - ✔ **Add credit** (U9.3) stops it. - On the power-off date, a server with **no apps and no databases is deleted instead** — so the banner says which of the two will happen to this server. - ✔ Credit added (B6.13) → the banner and both dates **go away** → `TOAST`. A server that was already powered off **stays off** — the page says "powered off — start it again", never "restored". 8. **Plan expired** (B7.12): - The page still **shows everything**, but every button is off with **"Plan has expired. Please renew it"**. - Only **Delete server** and **Add credit** still work → **Billing** (U9.3). - ✔ Credit added → the plan renews by itself and the buttons come back (B7.10). - The banner says what is coming for **this** server: - **managed** → powered off on the warning date, **deleted at the provider** on the lock date; - **self-managed** → only **removed from Central**, keeps running. **Screens that load from the server** (server panel and app panel): - **Always live:** show a skeleton while OSS answers; never show stale or fake data. - **Offline / unreachable server:** clear "server not reachable" state with **Retry** — the exact screen is **open** (backend Q3; "refresh, offline status, needs new token: decided later", B8). - **Bad or revoked token:** show "Needs new token" with a way to paste a new one — waiting on the same backend decision. - **OSS validation errors** appear under the right field; long actions (deploy, restore, SSL, install) show progress until done. - **Permissions:** every feature has view / manage for roles and shared servers (B10.22). **Plan limits** per feature (B10.21). **Delete protection** checked before any delete is sent to OSS (B3.6). - **Same screens as OSS:** reuse the OSS panel's own screens, only the connection goes through Central. **Risky server actions:** restart server, sudo, stop service, ban IP and clean disk always ask `CONFIRM`. ### U13.4 Server menu (in this order) - U13.8 **Server menu → Integrations** (after Server Sync): which Git accounts and backup storage are on this server, with **Add** `MODAL` and **Remove** `CONFIRM`. Pages in this order: Dashboard · Applications · Databases · System Users · Firewall · Cron Jobs · Fail2ban · System Logs · Services · PHP · Node.js · Settings · Disk Cleaner · Backups · Activity Log · Server Sync. ### Server menu — Dashboard `PAGE` — blocks in this order: | # | Block | Shows | |---|---|---| | 1 | **Server Overview** | Server name, status, IP with **Copy** | | 2 | **Configurations** | Kernel, runtimes, database versions | | 3 | **Specifications** | The server's hardware: CPU, memory, disk | | 4 | **Counts** | **Applications** · **Databases** · **Cron jobs** · **Application users** — each card opens its page | | 5 | **Server Metrics — Server Load** | Live load chart | | 6 | **Server Metrics — Server Resource Usage (%)** | Live CPU, memory, disk and swap usage in % | | 7 | **Database Metrics** | Live database charts | | 8 | **Server Metrics — I/O Activity** | Network and disk activity charts | - Also on the page: top processes → Stop `CONFIRM`, and the "Needs attention" list with fix buttons. - States: loading → skeletons per block · server not reachable → offline state with Retry (see "Screens that load from the server"). ### Server menu — Applications `PAGE`: the applications table (U14.1). ### Server menu — Databases `PAGE`: section 9. ### Server menu — System Users `PAGE`: 1. Table (username, shell, sudo, SSH, apps), search. 2. **Add user** `MODAL`: username, password or Generate, SSH key, more options (shell, sudo, SSH login) → `TOAST`. - A generated password is shown **once** here, with **Copy**. - The email about it carries no password (B11.15), so offer **Reset password** on the user afterwards. 3. Open a user: Set password `MODAL`, Sudo on `CONFIRM`, SSH login / shell switches `TOAST`, Add SSH key `MODAL`, Remove key `CONFIRM`. 4. Delete user → `TYPE-TO-CONFIRM` (username). ### Server menu — Firewall `PAGE`: 1. Banner: protected / not protected. **Turn on / off** `CONFIRM`. Default policy `CONFIRM`. 2. Quick-add tiles or **Create rule** `MODAL`: name, allow / block, protocol, port, from IP or "Only my IP". Port open to everyone → `CONFIRM`. 3. Rules table: on/off `TOAST`, Edit `MODAL`, Delete `CONFIRM`. 4. History list. ### Server menu — Cron Jobs `PAGE`: 1. Table (name, schedule, runs as, command, next run, active), filters. 2. **Add cron job** `MODAL`: name, user, app path, command, schedule picker or cron text, templates → `TOAST`. 3. Pause / Resume `TOAST`, Edit `MODAL`, Duplicate, View output `MODAL`, Delete `CONFIRM`. ### Server menu — Fail2ban `PAGE` (SSH and server jails; site login protection is in the app menu): 1. Not installed → **Install** → progress. 2. Jails on/off (risky ones → `CONFIRM` "This could lock you out"). 3. Banned addresses: Unban `CONFIRM`, Unban all `CONFIRM`, **Ban an address** `MODAL`. 4. Ban rules + "Never ban these" list → **Save** `TOAST`. ### Server menu — System Logs `PAGE`: pick a source → read with Live / Reload, filter, severity, lines, wrap, Copy, Download, **Clear log** `CONFIRM`. ### Server menu — Services `PAGE`: table (service, status, start on boot, CPU, memory). Start / Reload `TOAST`, Stop / Restart `CONFIRM`, Start on boot `CONFIRM`, View logs, Test configuration, Edit php.ini `MODAL`. ### Server menu — PHP `PAGE`: installed versions → **Install version** `MODAL` → progress. Make default `CONFIRM`. Remove `CONFIRM`. Extensions on/off `TOAST`. PHP settings → **Save** `TOAST`. ### Server menu — Node.js `PAGE`: installed versions → **Install version** `MODAL` → progress. Make default `CONFIRM`. Remove `CONFIRM`. **Update npm** `TOAST`. ### Server menu — Settings `PAGE` (in this order): 1. **Server:** name, timezone, auto clock. 2. **Access & security:** SSH port, root login, password or key only → "Check this before you save" `CONFIRM`. 3. **Memory:** swap size, Turn off swap `CONFIRM`, Redis limit and password, Remove password `CONFIRM`. 4. **Updates & restart:** automatic security updates, preferred time, **Restart server** `CONFIRM` → restart progress. 5. **Alert limits** (B11.13): CPU, memory, disk and the two load limits for **this server** → **Save** `TOAST`. **Reset to defaults** fills in the default values sent with the page — never numbers written into the screen. A line says who gets the alerts and that a load alert arrives at most once a day. - Unsaved changes bar with **Save** / **Discard**. ### Server menu — Disk Cleaner `PAGE`: disk bar → what can be cleaned with sizes → **Clean up** `CONFIRM`. **Automatic cleanup** `MODAL`. Recent cleanups. ### Server menu — Backups `PAGE` (every app on this server; one app → app menu): 1. Tabs: Overview / History / Restores. 2. **Set up backups** `MODAL`: app → what to back up → schedule → storage from Backup Storage (U12) (none → **Add storage** `MODAL`) → how many to keep → exclude folders → `TOAST`. 3. **Back up now** `TOAST`. Restore `CONFIRM`. Delete `CONFIRM`. ### Server menu — Activity Log `PAGE`: this server only — when, user, event; search, filter by type. Organization-wide list → **Audit log** (U17). ### Server menu — Server Sync `PAGE`: **Scan the server** → found items (websites, system users, databases, cron jobs, firewall rules …) → Dismiss / Undo → **Add to the panel** `CONFIRM` → results: added / skipped / failed. --- ## U14. Applications **Status:** From the OSS panel (Applications phase not written yet) **Purpose:** Users create and manage websites and apps on a server. **Opens from:** Server menu → Applications. Applications are listed **per server only** — there is no organization-wide applications page. 🔷 Intentional V8 difference from V7 (D5). **Build:** 🟡 WAITING ON BACKEND — needs the Servers phase (Central ↔ OSS panel connection) **Depends on:** Servers (U13); Integrations (U11) for Git apps; Backup Storage (U12) for backups. **Permissions:** App menu items the user isn't allowed to see are hidden. #### Screens | Screen | What's on it | Type | |---|---|---| | Applications | Table (Name, Application User, Primary Domain, PHP Version, Status, SSL, Size (MB), WordPress, Actions), filters, search | `PAGE` | | Create application | Type → fields → review → progress | `PAGE` | | App page | App menu with 12 items | `PAGE` | #### Flows ### Flow — List (U14.1) 1. Server menu → **Applications** `PAGE`: filters, search and the applications table, in this column order: | Column | Shows | |---|---| | **Name** | Application name — click it to open the **App page** (U14.3) | | **Application User** | The system user the app runs as | | **Primary Domain** | The app's primary domain | | **PHP Version** | PHP version of the app (empty for non-PHP apps) | | **Status** | Active / paused | | **SSL** | SSL on or off for the primary domain | | **Size (MB)** | Disk size of the app in MB | | **WordPress** | Whether it's a WordPress site | | **Actions** | **Visit site**, **Magic login** (WordPress only), **Pause** `CONFIRM`, **Delete** `TYPE-TO-CONFIRM` — same actions as the App page (U14.3) | 2. Click an app → **App page** (U14.3). **Create application** → 8.2. ### Flow — Create an application (U14.2, `PAGE`) 1. **Create application** → **Choose type** (WordPress, PHP, Git, …). Types this server can't host are greyed out with the reason. 2. **Fill in fields** for that type (domain, system user, PHP version …). Git apps: Git account (none → **Connect Git** `MODAL`) → repository → branch, each loaded after the one before (U14.5). 3. **Review** → **Create** → **Setup progress** `PAGE`. - ✔ Done → **App page** (U14.3) `TOAST`. - ✖ Failed → the reason + **Try again** / **Delete**. ### Flow — App page (U14.3) 1. **App page** `PAGE` with an **app menu** on the left (U14.4). 2. Top buttons: **Visit site**, **Magic login** `MODAL` (WordPress: pick admin), **Pause** `CONFIRM`, **Delete** → `TYPE-TO-CONFIRM` (domain) → **Applications** list `TOAST`. ### U14.4 App menu (in this order) Items the user isn't allowed to see are hidden. - U14.5 **Git deploy:** Git account (none → **Connect Git** `MODAL`) → repository → branch. Pages in this order: Dashboard · Domains & SSL · Environment · Workers · Files · Logs · Backups · Password Protection · Web Firewall · AI Bot Blocker · Fail2ban · Site Clone. - U14.4a **Only for some app types** (same menu): Deployment (Git apps), PHP settings (PHP apps), Staging (WordPress). ### App menu — Dashboard `PAGE` — blocks in this order (Bhavik, 2026-10-07): | # | Block | Shows | |---|---|---| | 1 | **Header** | App name + primary domain (opens the site), **SSL status** badge (e.g. "SSL Not Installed"), **WP Auto Login** (WordPress only), **Hide / Show details** | | 2 | **Server Overview** | Server (name + online dot), IP address with **Copy**, Server type (Self Managed / Managed), **Tag** (+ Add) | | 3 | **Application** | On / off switch (enable / disable the app), Application name, Primary domain (link), SSL status, **Tag** (+ Add) | | 4 | **Specifications** | OS, Web server, Server provider, Database | | 5 | **SFTP / SSH Credentials** | On / off switch · Host (**Copy**), Username (**Copy**), Password (**Copy to clipboard**, never shown), Port | | 6 | **Quick Backup** | **Instant backup** (+ create, 👁 view) · **Schedule backup** (+ create, 👁 view) | | 7 | **Database Details** | **phpMyAdmin Login** · **Access phpMyAdmin** · table: Database name, Size (MB), Remote access, View users, Remove database `CONFIRM` | | 8 | **Application Domains** | **+ Add a Domain** · refresh · table: Domain name (link), Primary domain (pick one), SSL, Actions (edit, on / off) | - Also on the page: the "Needs attention" list (no SSL, no backups …) with fix buttons. - States: loading → skeletons per block · no database → "No database attached" in block 7 · server not reachable → offline state with Retry. ### App menu — Domains & SSL `PAGE` (tabs Domains / SSL): 1. Domain list (primary, test domain). 2. **Add domain** `MODAL`: domain, type (alias or redirect + target and status code), DNS hint. 3. Make primary `CONFIRM`. Remove `CONFIRM`. 4. SSL status and renew date → **Install SSL** `MODAL` → progress → `TOAST`. ### App menu — Environment `PAGE`: `.env` editor (values hidden, Show) → **Save** `TOAST`. Panel-managed value → `CONFIRM`. Syntax error → not saved, line shown. History with **Restore** `CONFIRM`. ### App menu — Workers `PAGE`: table. **Add worker** `MODAL`. Start / Restart `TOAST`, Stop `CONFIRM`, Edit `MODAL`, Delete `CONFIRM`, View logs. ### App menu — Files `PAGE`: folder path, table, search. New file / folder `MODAL`, Upload, Edit (code editor), Download, Copy path, Rename / Move `MODAL`, Copy, Compress / Extract `MODAL`, Permissions `MODAL`, Delete `CONFIRM`. ### App menu — Logs `PAGE`: access / error / output → read, search, Download, **Clear log** `CONFIRM`. ### App menu — Backups `PAGE` (this app only): settings (storage from Backup Storage (U12), schedule, files / database) → **Back up now** `TOAST` → history → Download, **Restore** `CONFIRM`, Delete `CONFIRM`. ### App menu — Password Protection `PAGE`: switch + username + password → `TOAST`. Turn off `CONFIRM`. ### App menu — Web Firewall `PAGE`: switch → mode (Watch only / Block) → what it checks → allow / block lists → "What it caught" table. ### App menu — AI Bot Blocker `PAGE`: what to allow → own exceptions → AI bots that visited. ### App menu — Fail2ban `PAGE` (login protection for this site): **Turn on** → settings → **Save** `TOAST`. Banned addresses → Unban `CONFIRM`. **Remove protection** `CONFIRM`. ### App menu — Site Clone `PAGE`: what gets copied → new domain → **Create copy** `CONFIRM` → progress → done → "Before you use it" list → list of copies. --- ## U15. Databases **Status:** From the OSS panel **Purpose:** Users create databases and database users on a server. **Opens from:** Server menu → Databases. **Build:** 🟡 WAITING ON BACKEND — needs the Servers phase (Central ↔ OSS panel connection) **Depends on:** Servers (U13). #### Screens | Screen | What's on it | Type | |---|---|---| | Databases | Engines, list, adopt | `PAGE` | | Create database | Name, engine, user | `MODAL` | | Database page | Users, tables, exports, phpMyAdmin | `PAGE` | #### Flows ### Flow — Databases (U15.1–U15.3) 1. Server menu → **Databases** `PAGE` (U15.1): engines (missing → **Install** `CONFIRM` → progress), table (name, engine, size, users, app). Found databases → **Adopt** `CONFIRM`. 2. **Create** `MODAL` (U15.2): name, engine, optional user → **Create** → password shown **once** `MODAL` with **Copy** → list. - The email about new credentials **never contains the password** (B11.15) — it only says they are ready and to look in the panel. So this screen is the only place the password appears: say that in the pop-up, and offer **Reset password** on the database user afterwards for anyone who missed it. 3. Open a database → **Database page** `PAGE` (U15.3): Users, Tables, Exports, **Open in phpMyAdmin**. 4. Add user `MODAL` · Change password `MODAL` · Delete user `CONFIRM`. 5. Delete database → `TYPE-TO-CONFIRM` → list `TOAST`. --- ## U16. WordPress Blueprints **Status:** Not in the backend doc yet · Flow: ServerAvatar v7 · **Owned by Central** (Bhavik, 2026-10-06) **Purpose:** Users save a WordPress setup once and apply it to sites. Blueprints are stored and managed by Central, not by each server. **Opens from:** Sidebar → Blueprints. **Build:** 🟡 WAITING ON BACKEND — no backend phase yet **Depends on:** Applications (U14) — blueprints are applied to WordPress sites. **Open questions:** #11 #### Screens | Screen | What's on it | Type | |---|---|---| | Blueprints | Cards, filters, search | `PAGE` | | Create / edit blueprint | Theme, plugins, settings | `PAGE` | | Apply | Server → site → progress | `MODAL` | #### Flows **Every user** has this. ### Flow — Blueprints (U16.1–U16.3) 1. Sidebar → **Blueprints** `PAGE` (U16.1): cards, filters, search, sort. Bulk delete `CONFIRM`. 2. **Create blueprint** `PAGE` (U16.2): name, theme, plugins, language, time format, permalinks, advanced → **Save** → list `TOAST`. Leaving with unsaved changes → `CONFIRM`. 3. **Apply** `MODAL` (U16.3): server → WordPress site → **Apply** → progress with ✓ / ✗ steps. 4. Edit → same page as step 2. Delete → `CONFIRM`. --- ## U17. Audit log **Status:** Backend Phase B4.8 + B5.16 — requirements complete **Purpose:** Everyone with access can see who did what in the organization. **Opens from:** Sidebar → Audit log. **Build:** 🟢 READY — U3.8 and B5.16 define what is logged **Depends on:** Organizations (U3), Members (U6). Backend 4.8 and 5.16. **Permissions:** Only roles that allow it see this page. #### Screens | Screen | What's on it | Type | |---|---|---| | Audit log | Table, filters, search, export | `PAGE` | | Details | One event, before / after | `MODAL` | #### Flows Sidebar → **Audit log** `PAGE`. Everything people did in **this organization** (servers, apps, members, roles, billing, integrations, storage). Secrets and keys are never shown. ### Flow — Audit log 1. Table: when, who, action, what it was done to, IP. 2. Filters: person, type, date range. Search. 3. Click a row → **Details** `MODAL` (before / after values where there are any). 4. **Export** CSV (current filters) → `TOAST` "Export ready" + download. 5. Only roles that allow it see this page. - Each server also has its own **Activity Log** (U13.4 item 15). --- ## U18. Add-ons **Status:** Partly in the backend doc — **B7.26** says which add-ons a plan includes · Flow: ServerAvatar v7 **Purpose:** Users see every add-on in one place and buy or renew them. Each add-on has its own page (U19–U23); WordPress Blueprints is U16. **Opens from:** Sidebar → Add-ons. **Build:** 🟡 WAITING ON BACKEND — no add-on phase taken into this doc yet (B7.26 only) **Depends on:** Plans (U8) — add-ons show by plan; Billing (U9) — to buy. **Open questions:** #11 #### Screens | Screen | What's on it | Type | |---|---|---| | Screen | What's on it | Type | #### Add-on list Sorted by how the user gets it. **Card states:** Included · Buy · Upgrade needed · Active / expiring / expired. | Add-on | Who sees it | How the user gets it | What the user does | Backend | |---|---|---|---|---| | **Premium Hosting Care** (U19) | **Every user** | Always bought (1, 6 or 12 months); **never part of a plan** | Pay → Slack invite → cancel any time | No phase yet (v7) | | **WordPress Blueprints** | **Every user** | Free, owned by Central — its own page **U16** | Create and apply blueprints | No phase yet (v7) | | **WP Toolkit** (U20) (Object Cache Pro comes inside it — **no card of its own**) | By the user's plan | **Always bought; never part of a plan** (B7.26) | Turn on per site → Reports | No phase yet (v7) | | **Log Monitoring** (U21) | By the user's plan | Bought, or **Included** when the admin puts it in a plan (B7.26) | Turn on per site → Reports | B7.26 | | **Reseller panel** (U22) | By the user's plan | Bought, or **Included** in a plan (B7.26) | Licence key → Copy | B7.26 | | **White-label** (U23) | By the user's plan | Bought, or **Included** in a plan (B7.26) | Licence key → Copy (v7) | B7.26 | **Rules** - **Included with your plan** (B7.26): the admin can put **Log Monitoring, White-label and the Reseller panel** in a plan, so those cards read **Included** with nothing to buy. - **WP Toolkit and Premium Hosting Care are never part of a plan.** #### Flows Sidebar → **Add-ons** `PAGE`, one card per add-on. ### Flow — Buy or renew an add-on 1. Open **Add-ons** → cards. 2. **Buy / renew** → confirm-and-pay `CONFIRM` (same as U8.3) → `TOAST` → card shows Active. --- ## U19. Premium Hosting Care **Status:** Not in the backend doc yet · Flow: ServerAvatar v7 · **shown to every user, never part of a plan** **Purpose:** Users buy Premium Hosting Care for 1, 6 or 12 months. **Opens from:** Add-ons → Premium Hosting Care card. **Build:** 🟡 WAITING ON BACKEND — no backend phase yet (follows v7 until then) **Depends on:** Add-ons (U18); Plans (U8) — shown by plan; Billing (U9) — to buy. **Open questions:** #11 #### Screens | Screen | What's on it | Type | |---|---|---| | Premium Hosting Care card | Price, state, **Buy** / **Cancel** | part of Add-ons | | Choose period | 1, 6 or 12 months | `MODAL` | | Slack invite | Email for the Slack channel | `MODAL` | #### Flows ### Flow — Premium Hosting Care 1. Pick **1, 6 or 12 months** `MODAL` → pay `CONFIRM` → **Slack invite** `MODAL` (email) → `TOAST`. 2. Cancel `CONFIRM`. --- ## U20. WP Toolkit **Status:** Not in the backend doc yet · Flow: ServerAvatar v7 · **always bought, never part of a plan** (B7.26) · Object Cache Pro comes inside it **Purpose:** Users buy WordPress tools and turn them on per site. **Opens from:** Add-ons → WP Toolkit card. **Build:** 🟡 WAITING ON BACKEND — no backend phase yet (follows v7 until then) **Depends on:** Add-ons (U18); Plans (U8) — shown by plan; Billing (U9) — to buy. **Open questions:** #11 #### Screens | Screen | What's on it | Type | |---|---|---| | WP Toolkit card | Price, state, **Buy** | part of Add-ons | | Turn on per site | Pick the site | `CONFIRM` | | Reports | Per-site reports | `PAGE` | #### Flows ### Flow — WP Toolkit 1. Turn on per site `CONFIRM` → **Reports** `PAGE`. --- ## U21. Log Monitoring **Status:** Partly in the backend doc — **B7.26** lets a plan include it (v7 InsightHub) · Flow: ServerAvatar v7 · **handled by the Central Panel** (Bhavik, 2026-10-07) **Purpose:** Users turn on log reports per site. **Log Monitoring is handled by the Central Panel** — turning it on, the reports and the licence all live in Central; it is not an OSS-panel feature or a separate OSS service. **Opens from:** Add-ons → Log Monitoring card. **Build:** 🟡 WAITING ON BACKEND — no add-on phase taken into this doc yet (follows v7) **Depends on:** Add-ons (U18); Plans (U8) — shown by plan; Billing (U9) — to buy. **Open questions:** #11 #### Screens | Screen | What's on it | Type | |---|---|---| | Log Monitoring card | **Included** by plan or **Buy** | part of Add-ons | | Turn on per site | Pick the site | `CONFIRM` | | Reports | Per-site reports | `PAGE` | #### Flows ### Flow — Log Monitoring Same steps as WP Toolkit (U20), all inside **Central**: 1. Turn on per site `CONFIRM` → **Reports** `PAGE` (shown by Central). --- ## U22. Reseller panel **Status:** Partly in the backend doc — **B7.26** lets a plan include it (v7 self-hosted panel) · Flow: ServerAvatar v7 **Purpose:** Users get a licence key for their own reseller panel. **Opens from:** Add-ons → Reseller panel card. **Build:** 🟡 WAITING ON BACKEND — no backend phase yet (follows v7 until then) **Depends on:** Add-ons (U18); Plans (U8) — shown by plan; Billing (U9) — to buy. **Open questions:** #11 #### Screens | Screen | What's on it | Type | |---|---|---| | Reseller panel card | **Included** by plan or **Buy**; licence key with **Copy** | part of Add-ons | #### Flows ### Flow — Reseller panel 1. Licence key → **Copy** `TOAST`. --- ## U23. White-label **Status:** Partly in the backend doc — **B7.26** lets a plan include it · Flow: ServerAvatar v7 **Purpose:** Users put their own brand on the panel. **Opens from:** Add-ons → White-label card. **Build:** 🟡 WAITING ON BACKEND — no add-on phase taken into this doc yet (follows v7) **Depends on:** Add-ons (U18); Plans (U8) — shown by plan; Billing (U9) — to buy. **Open questions:** #11 #### Screens | Screen | What's on it | Type | |---|---|---| | White-label card | **Included** by plan or **Buy**; licence key with **Copy** | part of Add-ons | #### Flows ### Flow — White-label (v7) 1. Buy, or get it **Included** with a plan (B7.26) → card shows the **licence key** → **Copy** `TOAST`. --- ## U24. Referral **Status:** Not in the backend doc yet · Flow: ServerAvatar v7 **Purpose:** Users share a link and earn credit when friends sign up and pay. **Opens from:** User menu → Referral. **Build:** 🟡 WAITING ON BACKEND — no backend phase yet (follows v7 until then) **Depends on:** Sign up & login (U2, Flow G), Billing (U9) — rewards are credit. **Open questions:** #11 #### Screens | Screen | What's on it | Type | |---|---|---| | Referral | Link + clicks, sign-ups, approved | `PAGE` | #### Flows Not in the backend doc yet; follows v7. ### Flow — Referral page 1. User menu → **Referral** `PAGE`. 2. Referral link → **Copy** → `TOAST` "Copied". 3. Three cards: **clicks**, **sign-ups**, **approved**. 4. A referred user is **approved** once they are on a plan and have paid the set amount → the referrer gets **$X credit** (Billing → Wallet) + an email. 5. Program off → "The referral program is paused right now." - How the friend signs up: Flow G (U2). --- ## U25. Server tags **Status:** New in v8 — not in v7 or the backend doc yet · Tags need saving by the backend **Purpose:** Users with many servers find the right one fast: group servers with tags and see recently opened ones. **Opens from:** Servers list; Server page → Settings; organization switcher. **Build:** 🟡 WAITING ON BACKEND — tags must be saved by the backend **Depends on:** Servers (U13). **Permissions:** Tags: roles that can manage servers. Recently viewed: each user for themselves. **Open questions:** #11 #### Screens | Screen | What's on it | Type | |---|---|---| | Servers (tags bar) | Tag filter chips, Recently viewed | part of Servers | | Edit tags | Pick or create tags for a server | `MODAL` | | Manage tags | Rename, colour, delete tags | `MODAL` | #### Flows ### Flow — Tag a server 1. **Servers** list → server card **⋯** → **Edit tags** `MODAL` (also on **Server page → Rename / Edit tags**). 2. Pick existing tags or type a new one (name + colour) → **Save** → `TOAST` → tags show on the card. - ✖ Tag name too long (max 30) or the organization already has 50 tags → message under the field. 3. Tags belong to the **organization**, so the whole team sees the same tags. Only roles that can manage servers can change them. ### Flow — Filter by tag 1. **Servers** list → tag chips above the list (Production, Staging, Client A …) → click one or more → list shows servers with **any** of them. **Clear** resets. 2. The filter stays when the user leaves and comes back (saved in the browser). 3. **Manage tags** `MODAL` (from the chips bar): rename, change colour, **Delete** → `CONFIRM` "Removed from N servers". ### Flow — Recently viewed 1. The last 5 servers the user opened show as a row above the Servers list. Only for this user. ## A1. Admin: dashboard **Status:** Proposed — from the v7 admin panel; no backend phase yet **Purpose:** The ServerAvatar team sees how Central is doing at a glance. **Opens from:** Admin panel → Dashboard (first admin page). **Build:** 🟡 WAITING ON BACKEND — no backend phase describes it yet **Depends on:** Admin sign-in; reads users, servers and payments. **Permissions:** ServerAvatar admins only. #### Screens | Screen | What's on it | Type | |---|---|---| | Admin dashboard | Totals, payment summary, charts | `PAGE` | #### Flows ### Flow — Admin dashboard (proposed, from v7) 1. Admin signs in → **Admin dashboard** `PAGE`. 2. **Summary cards** and a **payment summary** (v7 summary). 3. Charts: **servers over time** and **payments over time**. 4. Breakdowns: servers by **web server**, by **provider**, by **OS version**. - Plan figures (users per plan, renewals, accounts close to lock) are in **Plan overview** (A4). --- ## A2. Admin: users **Status:** Proposed — from the v7 admin panel; no backend phase yet **Purpose:** Staff find any user account and help them. **Opens from:** Admin panel → Users. **Build:** 🟡 WAITING ON BACKEND — no backend phase describes it yet **Depends on:** Sign up & login (U2), Organizations (U3). **Permissions:** ServerAvatar admins only. #### Screens | Screen | What's on it | Type | |---|---|---| | Users | List, search, deleted users | `PAGE` | | User detail | Profile, statistics, organizations, servers, login history, activity | `PAGE` | | Create user | New account | `MODAL` | #### Flows ### Flow — Find and help a user (proposed, from v7) 1. Admin → **Users** `PAGE`: list with search. **Deleted users** listed apart. **Referrers** list. 2. Open a user → **User detail** `PAGE`: profile, statistics, organizations, servers, **login history**, **activity**. 3. Actions on the user (each from v7): - **Change status** → `CONFIRM` → `TOAST`. - **Log in as this user** → opens Central as them. - **2FA help**: turn 2FA off, regenerate backup codes (shown once to the admin, **never emailed** — B11.21). - **IP whitelist help**: switch on/off, add, edit, delete addresses. - **Payments**: add a payment by hand, update a payment (see A5). - **Charges**, **receipts**, **promo and redeem codes used**. - **Delete account** → `CONFIRM`. 4. **Create user** `MODAL` → `TOAST`. - A user's own plan and **free forever** are set from the user record — see A4. --- ## A3. Admin: payment gateways **Status:** Backend B6.1 — requirements written **Purpose:** Choose how users can pay. **Opens from:** Admin panel → Payment gateways. **Build:** 🟢 READY — backend B6.1 describes it **Depends on:** Billing (U9) — users see only gateways that are on. **Permissions:** ServerAvatar admins only. #### Screens | Screen | What's on it | Type | |---|---|---| | Payment gateways | Stripe, PayPal, Instamojo — on/off, test or live, keys | `PAGE` | #### Flows ### Flow — Set up a gateway (B6.1) 1. Admin → **Payment gateways** `PAGE`: one card each for **Stripe**, **PayPal**, **Instamojo**. 2. On a card: **on / off** switch, **test / live** mode, **keys** and **webhook secret** → **Save** → `TOAST`. 3. Users see **only gateways that are on** (B6.1). A gateway in test mode is labelled for users (U9). --- ## A4. Admin: plans **Status:** Backend Phase 7 — requirements complete **Purpose:** ServerAvatar admins create and manage plans, coupons and redeem codes. **Opens from:** Admin panel → Plans. **Build:** 🟢 READY — backend Phase 7 complete. Open: D-34 **Depends on:** Plans (U8) — users see only plans made here. **Permissions:** ServerAvatar admins only. **Open questions:** #6 #### Screens | Screen | What's on it | Type | |---|---|---| | Plans list | Order, status, prices, users | `PAGE` | | Create / edit plan | Name, prices, limits, features | `PAGE` | | Coupons | Code, discount, plans, expiry | `PAGE` | | Redeem-code batches | Batches, codes, download | `PAGE` | | Plan overview | Users per plan, renewals, close to lock | `PAGE` | | Expiry timing | Reminder start, warning day, lock day, weekdays | `PAGE` | #### Flows ServerAvatar admins only. ### Flow — Plan management (A4.1–A4.8) Covered below: Plans list · Create plan · Coupons · Edit a plan in use · Hide or archive · One user's plan · Free forever · Redeem-code batches · Plan overview · Expiry timing. ### Admin plans — Plans list Admin → **Plans** `PAGE` (A4.1): drag to order, status (Active, Hidden, Retired), prices, users on each plan. ### Admin plans — Create plan `PAGE` (A4.2): name, description, badge, periods and prices, trial on/off + days, limits, **feature list** (B7.2, each on / off with a number where needed), included add-ons, live preview → **Save** → list `TOAST`. - **Who can see it** (B7.14): **every plan is shown to all users**. The only exception is migration — a plan can be tied to a list of users, used to give migrated "restructured" users their own **Managed** and **Self Managed** plans. There is **no display name**: a plan has one name. - **Rename** (B7.1a): just a label — users keep the same plan. - **Add-ons** (B7.26): tick which add-ons this plan includes, from the list the backend sends. **WP Toolkit and Premium Hosting Care are not in that list** — they are handled separately. ### Admin plans — Coupons `PAGE` (B7.13): code, percent off, plans, first payment or recurring, expiry. Add / edit / delete `CONFIRM`. ### Admin plans — Edit a plan in use Edit a plan in use → **Save** → `CONFIRM` (A4.3): what changes (price B7.17, features or limits B7.18), that existing users keep today's terms until their next renewal and are told first, and how many users would be over a lower limit. ### Admin plans — Hide or archive **Hide / Archive** → `CONFIRM` (A4.4, B7.19): shows how many users keep it. - **System plans** (Free, Newbie, Pro, Master, Business, Managed, Self Managed, Legacy, Lifetime) can **never be deleted** — the button is off with the reason. - **Free** can't even be archived — free and free-forever users need it. - **Custom plans**: **Delete** → `TYPE-TO-CONFIRM`, allowed **only if nobody has ever been on it**; otherwise the button says "archive instead". ### Admin plans — One user's plan `PAGE` (A4.5, B7.20): from the user's admin record → price, limits, period, expiry → **Save** `TOAST`. ### Admin plans — Free forever (A4.6, B7.21): switch on the user's record → `CONFIRM` → `TOAST`. ### Admin plans — Redeem-code batches `PAGE` (A4.7, B7.23): **Create batch** `MODAL` (plan or credit, how many, expiry) → open a batch → used / unused + who → **Download list**. Switch off → `CONFIRM`. ### Admin plans — Plan overview `PAGE` (A4.8, B7.24): users per plan, upcoming renewals, accounts close to being locked → click → that user. ### Admin plans — Expiry timing `PAGE` (A4.9, B7.10–B7.12): how many days before expiry reminders start, the **warning day**, the **lock day**, and which **weekdays** reminders go out on → **Save** `TOAST`. Changing these changes the dates users see, so the page says so. --- ## A5. Admin: payments & receipts **Status:** Proposed — from the v7 admin panel; no backend phase yet **Purpose:** Staff see every payment and charge across all users. **Opens from:** Admin panel → Payments. **Build:** 🟡 WAITING ON BACKEND — no backend phase describes it yet **Depends on:** Billing (U9). **Permissions:** ServerAvatar admins only. #### Screens | Screen | What's on it | Type | |---|---|---| | All payments | Every user's payments, filtered by date | `PAGE` | | Add payment | Payment added by hand for a user | `MODAL` | #### Flows ### Flow — Payments (proposed, from v7) 1. Admin → **Payments** `PAGE`: payments from every user, filter by date. 2. From a user (A2): **Add payment** `MODAL` → `TOAST`; **update** a payment. 3. A user's **charges** by status, and their **receipts**. --- ## A6. Admin: platform settings **Status:** Proposed — from the v7 admin panel; no backend phase yet **Purpose:** General settings that change what users see and pay. **Opens from:** Admin panel → Settings. **Build:** 🟡 WAITING ON BACKEND — no backend phase describes it yet **Depends on:** Billing (U9), Referral (U24), Applications (U14). **Permissions:** ServerAvatar admins only. #### Screens | Screen | What's on it | Type | |---|---|---| | Settings | Grouped settings tabs | `PAGE` | #### Flows ### Flow — Platform settings (proposed, from v7) 1. Admin → **Settings** `PAGE`, in groups (each from v7's admin): - **Billing:** sign-up credit (paid and free), minimum top-up, refund period. (v7's monthly-invoice settings — due day, grace period, invoice prefix — are left out: that invoice billing is switched off in v7's code.) - **Referral:** on/off, reward for the new user, reward for the referrer, amount the friend must pay first (U24). - **Application types:** which app types users can create (U14.2). - **Site-wide message:** a banner shown to all users; remove it. - **Test domain:** the domain used for test domains. - **Default web pages:** the pages servers show by default. - **Team contacts:** support email and Slack channel. 2. Each group → **Save** → `TOAST`. - Trial days and expiry timing are set in **Plans** (A4). --- ## A7. Admin: promo codes **Status:** Proposed — from the v7 admin panel; no backend phase yet **Purpose:** Codes that give users a discount or free credit. **Opens from:** Admin panel → Promo codes. **Build:** 🔴 NEEDS YOUR DECISION — v7 promo codes overlap with plan coupons (B7.13); decide whether both are kept **Depends on:** Plans (U8), Billing (U9). **Permissions:** ServerAvatar admins only. #### Screens | Screen | What's on it | Type | |---|---|---| | Promo codes | List, on/off options, delete | `PAGE` | | Create promo code | Type, code, amount, limits, who can use it | `MODAL` | #### Flows ### Flow — Promo codes (proposed, from v7) 1. Admin → **Promo codes** `PAGE`: list. 2. **Create** `MODAL` (v7 fields): - type: **discount** or **free credit**; code; description; - discount % or free-credit amount (+ how many days the credit lasts); - limit: number of uses **or** days valid; - who can use it: new customers, existing customers, everyone. - ✖ v7 messages: "Put something in one of these two that expires in days or usable." · "Expires in days and usage any one use." 3. Switch an option on/off on a row → `TOAST`. **Delete** → `CONFIRM`. - Plan **coupons** (B7.13) and **redeem codes** (B7.23) are in A4. --- ## A8. Admin: organizations & servers **Status:** Proposed — from the v7 admin panel; no backend phase yet **Purpose:** Staff see all organizations and servers to support users, and **transfer a server** to another organization or another user (admin only, as v7). **Opens from:** Admin panel → Organizations / Servers. **Build:** 🟡 WAITING ON BACKEND — needs the Servers phase and an admin phase **Depends on:** Servers (U13), Organizations (U3). **Permissions:** ServerAvatar admins only. #### Screens | Screen | What's on it | Type | |---|---|---| | Organizations | All organizations; backups per organization | `PAGE` | | Servers | All servers, usage and load; **Transfer server** per row | `PAGE` | | Transfer server | Same user's other organization, or another user's organization | `MODAL` | | Install logs | Server install logs | `PAGE` | #### Flows ### Flow — Organizations & servers (proposed, from v7) 1. Admin → **Organizations** `PAGE` → open one → its **backups** (delete a backup → `CONFIRM`). 2. Admin → **Servers** `PAGE`: all servers with **usage** and **load**. 3. **Install logs** `PAGE`: list → open a log → read it; **Delete** old logs → `CONFIRM`. ### Flow — Transfer server (admin only, v7) **Only ServerAvatar admins can transfer a server** (Bhavik, 2026-10-07). Users never see a Transfer button — not owners, members or shared users. A user who wants a server moved asks support. 1. Admin → **Servers** → server row → **Transfer server** `MODAL` → pick the kind: - **To another organization of the same user** — pick one of the owner's organizations. - ✖ "The server organization is the same as the requested organization." · "The requested organization could not be found in the user's account." · "The user is ineligible for server transfer." - **To another user's account** — search the user → pick one of their organizations. - ✖ "Organization not found in selected user account." · "You cannot perform a self-account transfer." · "Subscription plan not found." · "You cannot add more than servers in this organization." · "Insufficient credits in the selected account. Please add $ before transferring this server." 2. Review: server, from (user · organization) → to (user · organization), what moves with it (applications, databases, people it is shared with) → **Transfer** → `CONFIRM`. 3. ✔ `TOAST` "The server has been transferred successfully." The server now shows in the new organization; the old organization no longer lists it. Recorded in the admin activity log (A10). 4. Not defined by backend yet: whether both users are notified, and what happens to roles given on that server. - v7's agent tools (agent version, agent update) don't apply: V8 servers run the OSS panel. --- ## A9. Admin: affiliate program **Status:** Proposed — from the v7 admin panel; no backend phase yet (affiliate is a later phase in the backend doc) **Purpose:** Run the affiliate program. **Opens from:** Admin panel → Affiliates. **Build:** 🟡 WAITING ON BACKEND — affiliate is "its own phase" in the backend doc **Depends on:** Referral (U24), Billing (U9). **Permissions:** ServerAvatar admins only. #### Screens | Screen | What's on it | Type | |---|---|---| | Affiliate dashboard | Summary, clicks graph, transactions | `PAGE` | | Affiliates | List, create, users per affiliate | `PAGE` | | Payouts & commissions | Payout history, commissions | `PAGE` | | Marketing assets | Banners and logos | `PAGE` | #### Flows ### Flow — Affiliates (proposed, from v7) 1. Admin → **Affiliate dashboard** `PAGE`: summary, graph, transactions; **active affiliates**. 2. **Affiliates** `PAGE`: list, **create** an affiliate, open one → its **users**. 3. A user's affiliate application → **approve** (verification). 4. **Payouts**: record a payout, delete one → `CONFIRM`. **Commissions**: list; delete a wrong one → `CONFIRM`. 5. **Marketing assets**: upload, delete → `CONFIRM`. --- ## A10. Admin: activity log **Status:** Proposed — from the v7 admin panel; no backend phase yet **Purpose:** See what admins did in the admin panel. **Opens from:** Admin panel → Activity log. **Build:** 🟡 WAITING ON BACKEND — no backend phase describes it yet **Depends on:** Admin panel. **Permissions:** ServerAvatar admins only. #### Screens | Screen | What's on it | Type | |---|---|---| | Admin activity log | Admin actions list | `PAGE` | #### Flows ### Flow — Admin activity log (proposed, from v7) 1. Admin → **Activity log** `PAGE`: the admin actions list (v7 "admin activities"). - The organization's own log for users is the **Audit log** (U17). --- ## A11. Admin: staff roles **Status:** Proposed — new idea for V8, not in v7 or the backend doc (also proposed in Frontend 1's plan) **Purpose:** Give each staff member only the admin areas they need. **Opens from:** Admin panel → Staff roles. **Build:** 🔴 NEEDS YOUR DECISION — proposed feature, not a confirmed requirement **Depends on:** Admin users (A2). **Permissions:** ServerAvatar admins only. #### Screens | Screen | What's on it | Type | |---|---|---| | Staff roles | Roles and what each can see and do | `PAGE` | | Create / edit role | Name + permissions per admin area | `MODAL` | #### Flows ### Flow — Staff roles (proposed) 1. Admin → **Staff roles** `PAGE`: list of roles and the staff on each. 2. **Create role** `MODAL`: name + which admin areas it can see and change → **Save** → `TOAST`. 3. Assign roles to a staff member from **Users** (A2). - Proposed only — the backend doc has no staff roles. --- ## A12. Admin: panel health **Status:** Proposed — new idea for V8, not in v7 or the backend doc **Purpose:** Spot servers whose OSS panel is old or keeps failing to connect. **Opens from:** Admin panel → Panel health. **Build:** 🔴 NEEDS YOUR DECISION — proposed feature, not a confirmed requirement **Depends on:** Servers (U13). **Permissions:** ServerAvatar admins only. #### Screens | Screen | What's on it | Type | |---|---|---| | Panel health | Servers with an old OSS panel version or repeated connection failures | `PAGE` | #### Flows ### Flow — Panel health (proposed) 1. Admin → **Panel health** `PAGE`: servers with an **old OSS panel version** and servers that **keep failing to connect**. 2. Click a row → that server in **Organizations & servers** (A8). - Proposed only — not in v7 or the backend doc. ## Messages reference Every user-facing message that appears in the flows, in one list — built automatically from the flows, so the wording is always the same as in the flow. **Key** shows "key to be defined": no translation keys are agreed yet. The messages also stay inside their own flows. [[MESSAGES-TABLE]] --- ## Reference pages Deeper technical pages on the full spec site (they open in the same tab): - [API architecture](../api-architecture.html) - [Data relationships](../data-relationships.html) - [Routes](../routes.html) - [Navigation](../navigation.html) - [Security](../security.html) - [Testing](../testing.html) - [Dependencies](../dependencies.html) - [Migration from v7](../v7-migration.html) - [Languages](../i18n.html) --- ## Glossary - **OSS panel** — the open-source ServerAvatar panel installed on every server. Central reads and changes a server's data live through it. - **Managed server** — a server ServerAvatar provides, billed by the hour from **paid credit**. Users can't create new ones in V8; existing ones keep working. Its OSS panel is **not accessible** to the user; it is managed only from Central. When a plan expires it is powered off, then deleted at the provider. - **Self-managed server** — the user's own server (own machine or their own cloud account). When a plan expires it is only removed from Central and keeps running. - **Paid credit** — credit bought with money (top-ups, auto-recharge). The only credit that pays managed-server hours. - **Free credit** — credit not bought, given by ServerAvatar (v7 gives some at sign-up). - **Promo credit** — credit from promo codes; it has an expiry date and can't pay managed-server hours. - **Shared user** — someone outside the organization given access to **one** server with chosen permissions. They can never create, delete or share that server. - **Organization owner** — the person who created the organization (or received it by transfer). Their plan covers all organizations they own; only they can rename or delete the organization or transfer it.