================================================================================ WORKSPACE RESEARCH - COMPLETE FINDINGS INDEX ================================================================================ RESEARCH COMPLETED: 2025-12-05 DOCUMENTATION SAVED TO: /mnt/data-disk1/archie-platform-v2/docs/ ================================================================================ PRIMARY DOCUMENTS CREATED ================================================================================ 1. WORKSPACE_PIXEL_DESIGN_SPECIFICATION.md (27KB) - Full comprehensive specification - Complete data model documentation - All required UI pages with wireframes - Design system requirements - API endpoint specifications - Implementation priority matrix 2. WORKSPACE_RESEARCH_SUMMARY.md (Quick Reference) - Executive summary - Data structure diagram - Priority page list - API endpoints summary - Next steps for design phase ================================================================================ KEY FINDINGS ================================================================================ TERMINOLOGY: - "Firms" = Workspaces/Organizations/Tenants - "Workspace" = Firm in the codebase - Multi-tenant system: 1 Firm → N Users DATA MODEL STATUS: ✓ Complete firm/workspace table (UUID primary key) ✓ User-firm relationships (1:N) ✓ Subscription tiers (starter, professional, enterprise, trial) ✓ Feature flags (JSONB) ✓ Soft deletes support ✓ Full-text search on name (trigram index) BACKEND SERVICES STATUS: ✓ Organization Manager (organization_manager.py) ✓ User Provisioning (provisioning.py) ✓ WorkOS SSO Integration (workos_models.py) ✓ Auth Router (auth_router.py) ✓ Database schema complete FRONTEND STATUS: ✗ No workspace switcher ✗ No team management pages ✗ No workspace settings UI ✗ No invitation flows ✗ No subscription management UI API ENDPOINTS: ✗ Missing all workspace CRUD endpoints ✗ Missing team member management endpoints ✗ Missing subscription endpoints ✗ Missing feature flag management endpoints ================================================================================ DESIGN REQUIREMENTS IDENTIFIED ================================================================================ PRIORITY 1 (Critical/Must-Have): 1. Workspace Switcher (navigation dropdown) 2. Team Members Management Page (list, invite, roles) 3. Workspace Settings Page (basic info, plan, features) PRIORITY 2 (Important/Should-Have): 4. Invite User Modal 5. Create Workspace Modal 6. Subscription/Billing UI 7. Directory Sync Status Display PRIORITY 3 (Nice-to-Have): 8. Audit Log Viewer 9. Workspace Branding/Avatar 10. Custom Role Management 11. Activity Timeline ================================================================================ DESIGN SYSTEM REFERENCE ================================================================================ COLORS (Already Defined): - Primary Blue: #15b1cd - Secondary Background: #f5f6fa - Status Green: #71d481 - Status Red: #fb6060 - Status Amber: #8f6c1a - Grey Scale: 6 shades (#000626 to #fafafc) TYPOGRAPHY (10 Levels): - Display: 48px - H1: 40px - H2: 32px - H3: 24px - H4: 20px - Body: 16px - Small: 14px - Tiny: 12px - XSmall: 12px - Column Header: 10px SPACING: Tailwind 4px base unit BORDER RADIUS: 8px standard, 12px for large elements SHADOWS: Defined in design system ================================================================================ CRITICAL DATABASE TABLES ================================================================================ FIRMS TABLE: - id (UUID primary key) - name (VARCHAR 255, searchable) - subscription_tier (starter|professional|enterprise|trial) - max_users (Integer) - max_queries_per_day (Integer) - max_queries_per_minute (Integer) - features (JSONB with feature toggles) - metadata (JSONB for extensions) - created_at, updated_at, deleted_at (soft delete) USERS TABLE: - id (UUID) - firm_id (UUID FK) - email (VARCHAR 255) - role (user|firm_admin|admin|read_only) - external_id (WorkOS user ID) - is_active (Boolean) - preferences (JSONB) - metadata (JSONB) - created_at, updated_at, deleted_at ================================================================================ REQUIRED API ENDPOINTS (NOT YET IMPLEMENTED) ================================================================================ FIRM CRUD: POST /api/v1/firms Create firm GET /api/v1/firms List user's firms GET /api/v1/firms/:firm_id Get firm details PUT /api/v1/firms/:firm_id Update firm DELETE /api/v1/firms/:firm_id Delete firm (soft) TEAM MEMBERS: GET /api/v1/firms/:firm_id/members List members POST /api/v1/firms/:firm_id/members Invite user PUT /api/v1/firms/:firm_id/members/:user_id Update role DELETE /api/v1/firms/:firm_id/members/:user_id Remove user SUBSCRIPTION & USAGE: GET /api/v1/firms/:firm_id/subscription PUT /api/v1/firms/:firm_id/subscription GET /api/v1/firms/:firm_id/usage FEATURES: GET /api/v1/firms/:firm_id/features PUT /api/v1/firms/:firm_id/features/:feature_id ================================================================================ SOURCE FILE REFERENCES ================================================================================ BACKEND FILES: - /src/auth/organization_manager.py (485 lines, full org logic) - /src/auth/provisioning.py (238 lines, user provisioning) - /src/auth/providers/workos_models.py (178 lines, data models) - /src/auth/providers/workos_sso_provider.py (OAuth implementation) - /src/api/routers/auth_router.py (Authentication endpoints) - /src/api/routers/workos_oauth_router.py (OAuth endpoints) - /src/api/routers/query_router.py (Query orchestration) DATABASE FILES: - /docs/DATABASE_SCHEMA.sql (Complete schema, 400+ lines) - /infrastructure/docker/development/init-scripts/01-init-database.sql - /src/services/file-ingestion/models/tenant.py (Tenant model) - /src/services/file-ingestion/models/user.py (User model) FRONTEND FILES: - /ui/src/lib/auth/auth-context.tsx (Auth state management) - /ui/src/services/workos.ts (WorkOS service) - /ui/src/services/auth.ts (Auth service) DESIGN REFERENCE: - /docs/UI_UX_RECONSTRUCTION_GUIDE.md (1,900+ lines, full design system) - /docs/UI_RECONSTRUCTION_SUMMARY.md (Executive summary) ================================================================================ IMPLEMENTATION ROADMAP (RECOMMENDED) ================================================================================ PHASE 1: Foundation (Week 1) - Extract design system tokens (colors, typography, spacing) - Create base component library (Button, Input, Card, Badge) - Setup workspace context/state management PHASE 2: Core Components (Week 2) - Workspace Switcher component - Team Members list component - Invite User modal component - Create Workspace modal component PHASE 3: Pages (Week 3) - Workspace Settings page - Team Members Management page - Workspace Details page PHASE 4: Features (Week 4) - Subscription UI - Directory sync status display - Feature toggle display - Usage metrics display PHASE 5: Polish & Integration (Week 5) - Responsive design - Dark mode support - Animations/transitions - Error states and loading states ================================================================================ INTEGRATION CHECKLIST ================================================================================ BEFORE DESIGN: - Review DATABASE_SCHEMA.sql (firms, users, subscriptions) - Review auth_context.tsx (current state management) - Review UI_UX_RECONSTRUCTION_GUIDE.md (design system) - Review organization_manager.py (backend capabilities) DURING DESIGN: - Keep firm_id multi-tenancy isolation in mind - Design for role-based access (firm_admin vs user vs read_only) - Consider soft deletes (deleted_at field) - Plan for JSONB extensible fields (metadata, features) BEFORE HANDOFF TO DEV: - Document all page layouts and flows - Specify component state variations - Provide interaction specifications - List all data fields needed from API - Specify error states and edge cases ================================================================================ QUICK REFERENCE - WHAT TO DESIGN ================================================================================ PAGES (5 main): 1. Workspace Switcher (navigation dropdown) 2. Workspace Settings Page (info, subscription, features, sync) 3. Team Members Page (list, invite, manage roles) 4. Invite User Modal (form for adding members) 5. Create Workspace Modal (form for new workspace) SUPPORTING ELEMENTS: - Workspace card component (for lists) - Team member row component (for tables) - Role badge component - Plan badge component - Feature toggle component - Status indicator component INTERACTIONS: - Switch between workspaces - Invite users to workspace - Create new workspace - Remove team members - Change user roles - Update workspace settings - View subscription/billing info DATA TO DISPLAY: - Workspace name, avatar, plan - User list with roles and status - Subscription plan and usage - Feature flags and toggles - Directory sync status - Member count vs quota - Join dates and last activity ================================================================================ DELIVERABLES READY ================================================================================ ✓ Complete workspace data model documentation ✓ Database schema with all tables and fields ✓ Backend services overview ✓ Design system (colors, typography, spacing) ✓ Required page specifications with wireframes ✓ Component breakdown with data requirements ✓ API endpoint specifications ✓ Implementation priority matrix ✓ Technical integration points identified ✓ File location references ================================================================================ STATUS: RESEARCH PHASE COMPLETE Ready for: Pixel Design Phase Next Step: Create high-fidelity mockups based on specifications ================================================================================