Initial commit: The Collective Hub planning documentation
This commit is contained in:
@@ -0,0 +1,265 @@
|
||||
# Admin UX Planning Document — The Collective Hub
|
||||
|
||||
## Design Principles
|
||||
|
||||
- **Practical over fancy.** A basic form that works beats a beautiful UI that's confusing.
|
||||
- **One page per concern.** Settings, branding, homepage, links, events, assets — each gets its own admin page.
|
||||
- **Instant feedback.** Save button with clear success/error state. No ambiguous "it might have saved" experiences.
|
||||
- **Site-scoped by default, super admin cross-site.** Regular admins see only their site. Super admins (David) can access any site's admin panel.
|
||||
- **Mobile-accessible but desktop-first.** Admins will primarily manage their site from a desktop/laptop.
|
||||
|
||||
---
|
||||
|
||||
## Login Flow
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant A as Admin/Owner
|
||||
participant S as Site
|
||||
participant D as Discord
|
||||
|
||||
A->>S: Clicks "Admin" or visits /admin
|
||||
S->>S: Check session
|
||||
S-->>A: Redirect to /login (if not logged in)
|
||||
A->>S: Clicks "Login with Discord"
|
||||
S->>D: Redirect to Discord OAuth
|
||||
D->>A: Authorize screen
|
||||
A->>D: Approve
|
||||
D->>S: Callback with code
|
||||
S->>S: Exchange code, get user info
|
||||
S->>S: Check OWNER_DISCORD_ID match
|
||||
S->>S: Create/confirm membership (owner role)
|
||||
S->>S: Create session
|
||||
S-->>A: Redirect to /admin
|
||||
```
|
||||
|
||||
### Login Page
|
||||
|
||||
A simple, centered page with:
|
||||
- Site logo (or site name if no logo set)
|
||||
- "Login with Discord" button (prominent, branded)
|
||||
- Brief explanation: "Sign in to manage [Site Name]"
|
||||
- No other login methods in V1
|
||||
|
||||
### First Owner Login
|
||||
|
||||
1. Owner visits `/login`
|
||||
2. Logs in with Discord
|
||||
3. System detects their Discord ID matches `OWNER_DISCORD_ID`
|
||||
4. Owner membership created automatically
|
||||
5. Redirected to admin dashboard
|
||||
6. Dashboard shows: "Welcome, [username]. You are the owner of [Site Name]."
|
||||
|
||||
### Super Admin Login
|
||||
|
||||
Super admins (Discord IDs listed in `SUPER_ADMIN_DISCORD_IDS`):
|
||||
- Can log in to any site's admin panel regardless of `OWNER_DISCORD_ID`
|
||||
- See a "Super Admin" badge or indicator in the admin UI
|
||||
- Have a "View All Sites" link (placeholdered until Phase 4 super admin dashboard)
|
||||
- Can perform all actions a site owner can
|
||||
|
||||
### Non-Owner Login (Before Role Management)
|
||||
|
||||
If a non-owner, non-super-admin logs in (Phase 1-4 before role management exists):
|
||||
- They are authenticated but have no membership for the current site
|
||||
- Show: "You don't have access to manage this site. Contact the site owner."
|
||||
- No admin pages are accessible
|
||||
|
||||
### Session Behavior
|
||||
|
||||
- Session persists across browser restarts (HTTP-only cookie via Better Auth)
|
||||
- Logout button in admin nav clears session
|
||||
- Session expiry: Better Auth defaults (configurable)
|
||||
|
||||
---
|
||||
|
||||
## Admin Layout
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────┐
|
||||
│ [Logo/Name] Admin Panel [User] [Logout] │
|
||||
├──────────┬───────────────────────────────────┤
|
||||
│ │ │
|
||||
│ Dashboard│ │
|
||||
│ Settings │ Content Area │
|
||||
│ Branding │ │
|
||||
│ Homepage │ │
|
||||
│ Links │ │
|
||||
│ Events │ │
|
||||
│ Assets │ │
|
||||
│ Team │ │
|
||||
│ │ │
|
||||
└──────────┴───────────────────────────────────┘
|
||||
```
|
||||
|
||||
- **Left sidebar:** Navigation links. Highlight current page. Collapse on mobile (hamburger).
|
||||
- **Top bar:** Site name, current user avatar + name, logout button.
|
||||
- **Content area:** The active page content.
|
||||
|
||||
---
|
||||
|
||||
## Admin Pages
|
||||
|
||||
### Dashboard (`/admin`)
|
||||
|
||||
**Purpose:** Quick overview and navigation hub.
|
||||
|
||||
**Content:**
|
||||
- Welcome message with owner name
|
||||
- Site status: "Your site is live at [URL]"
|
||||
- Quick stats (future): event count, page views
|
||||
- Quick links to common actions: "Edit Homepage", "Manage Events"
|
||||
- In V1, this can be minimal—a simple landing page after login
|
||||
|
||||
### Settings (`/admin/settings`)
|
||||
|
||||
**Purpose:** Basic site identity.
|
||||
|
||||
**Fields:**
|
||||
- Site name (text input)
|
||||
- Tagline (text input)
|
||||
- Save button
|
||||
|
||||
**Behavior:**
|
||||
- Load current values from `siteSettings` JSON
|
||||
- Save updates the JSON blob
|
||||
- Success toast: "Settings saved"
|
||||
- Error toast with specific message on failure
|
||||
|
||||
### Branding (`/admin/branding`)
|
||||
|
||||
**Purpose:** Visual identity and theme.
|
||||
|
||||
**Fields:**
|
||||
- Logo: file upload button OR manual URL input (Phase 2: asset picker from library)
|
||||
- Background image: same pattern
|
||||
- Favicon: file upload
|
||||
- Theme preset: dropdown (Dark, Light, Custom)
|
||||
- Accent color: color picker + hex input
|
||||
- Background color: color picker + hex input
|
||||
- Text color: color picker + hex input
|
||||
|
||||
**Behavior:**
|
||||
- Color pickers show live preview of the color
|
||||
- "Preview" link opens public site in new tab
|
||||
- Save updates `siteSettings.branding` and `siteSettings.theme` in JSON
|
||||
|
||||
### Homepage (`/admin/homepage`)
|
||||
|
||||
**Purpose:** Edit public homepage content.
|
||||
|
||||
**Fields:**
|
||||
- Hero title (text input)
|
||||
- Hero subtitle (text input)
|
||||
- About/intro text (textarea, plain text or basic Markdown)
|
||||
- Primary button text (text input, e.g., "Join Discord")
|
||||
- Primary button link (URL input)
|
||||
- Toggle: Show next event section (checkbox)
|
||||
- Toggle: Show schedule section (checkbox)
|
||||
|
||||
**Behavior:**
|
||||
- All fields are optional — empty fields are hidden on the public site
|
||||
- Save updates `siteSettings.homepage` in JSON
|
||||
- "View site" link opens public homepage in new tab
|
||||
|
||||
### Links (`/admin/links`)
|
||||
|
||||
**Purpose:** Manage navigation and social links.
|
||||
|
||||
**Sub-pages or tabs:**
|
||||
- **Nav Links tab:** Table of links with label, URL, position (header/footer), sort order
|
||||
- **Social Links tab:** Table of links with platform (dropdown: Discord, Twitter/X, YouTube, Twitch, etc.), label, URL, sort order
|
||||
|
||||
**Behavior:**
|
||||
- Add new link: inline form at top or modal
|
||||
- Edit: inline or modal
|
||||
- Delete: with confirmation
|
||||
- Drag-to-reorder (nice-to-have, manual sort order numbers are fine for V1)
|
||||
- Save is per-link or "Save all changes" button
|
||||
|
||||
### Events (`/admin/events`)
|
||||
|
||||
**Purpose:** Manage event listings.
|
||||
|
||||
**List view:**
|
||||
- Table: title, date/time, status (published/draft), actions (edit/delete)
|
||||
- "Add Event" button
|
||||
- Filter: upcoming, past, drafts
|
||||
|
||||
**Event edit/create form:**
|
||||
- Title (text, required)
|
||||
- Description (textarea)
|
||||
- Event type (dropdown: Screening, Watch Party, Meetup, Other)
|
||||
- Start time (datetime picker)
|
||||
- End time (datetime picker, optional)
|
||||
- Timezone (dropdown, defaults to `America/New_York`)
|
||||
- Location (text, e.g., "Discord Stage")
|
||||
- External link (URL)
|
||||
- Event image (upload or URL)
|
||||
- Published toggle
|
||||
|
||||
**Behavior:**
|
||||
- Events sorted by start time
|
||||
- Draft events hidden from public site
|
||||
- Delete with confirmation
|
||||
- Basic validation: title required, start time required
|
||||
|
||||
### Assets (`/admin/assets`)
|
||||
|
||||
**Purpose:** Browse and manage uploaded files.
|
||||
|
||||
**List view:**
|
||||
- Grid or table of assets with thumbnail, filename, type, size, date
|
||||
- Search/filter by filename
|
||||
- Click to copy CDN URL
|
||||
- Delete with confirmation
|
||||
|
||||
**Upload:**
|
||||
- Drag-and-drop zone or file input
|
||||
- Accept: image/webp, image/png, image/jpeg
|
||||
- Max size: configurable (e.g., 5MB)
|
||||
- Progress indicator during upload
|
||||
- Success: asset appears in list
|
||||
|
||||
**Note:** Asset upload with webp conversion is available from Phase 1. The asset library is fully functional from day one — no manual URL phase.
|
||||
|
||||
### Team (`/admin/team`) — Phase 5+
|
||||
|
||||
**Purpose:** Manage admins and editors.
|
||||
|
||||
**List view:**
|
||||
- Table: user avatar, username, role, actions (change role, remove)
|
||||
|
||||
**Add member:**
|
||||
- Input for Discord username or ID
|
||||
- Role dropdown
|
||||
- "Add" button
|
||||
|
||||
**Behavior:**
|
||||
- Owner cannot be removed or demoted
|
||||
- Owner can promote/demote/remove admins and editors
|
||||
- Changes take effect immediately
|
||||
|
||||
---
|
||||
|
||||
## Error States & Edge Cases
|
||||
|
||||
| Situation | Behavior |
|
||||
|-----------|----------|
|
||||
| Save fails (network error) | Show error toast, keep form data intact |
|
||||
| Save fails (validation) | Highlight invalid fields, show specific messages |
|
||||
| Session expires while editing | Redirect to login on next action, preserve intended destination |
|
||||
| Concurrent editing (two admins) | Last write wins in V1 (no conflict detection) |
|
||||
| Loading state | Skeleton/spinner while data loads |
|
||||
| Empty state | "No events yet. Create your first event!" with action button |
|
||||
| CDN unreachable | Admin still works; image uploads fail with clear error |
|
||||
|
||||
---
|
||||
|
||||
## What to Avoid
|
||||
|
||||
- **Multi-step wizards.** Single-page forms are simpler.
|
||||
- **Inline editing everywhere.** Form pages with clear save buttons are more predictable.
|
||||
- **Real-time preview in V1.** A "preview" link to the public site is sufficient.
|
||||
- **Over-designed dashboards.** The admin panel is a tool, not a product demo.
|
||||
- **Custom permission UIs in V1.** Owner + super admin access is sufficient until Phase 5.
|
||||
Reference in New Issue
Block a user