# Milestone 5: Developer Portal Frontend **Status**: Planning **Goal**: Web interface for developer account and app management. --- ## Overview The developer portal is the primary interface for developers to manage their accounts, create apps, submit versions, and view analytics. --- ## Pages Required ### Public Pages | Page | URL | Purpose | |------|-----|---------| | Landing | `/` | Marketing, sign up CTA | | Sign In | `/login` | OAuth + password login | | Sign Up | `/register` | Create account | | Docs | `/docs/*` | Documentation (separate site?) | ### Authenticated Pages | Page | URL | Purpose | |------|-----|---------| | Dashboard | `/dashboard` | App list, quick stats | | App Details | `/apps/:id` | Single app overview | | App Settings | `/apps/:id/settings` | Edit app metadata | | App Versions | `/apps/:id/versions` | Version history | | Submit Version | `/apps/:id/versions/new` | Upload new version | | App Analytics | `/apps/:id/analytics` | Telemetry dashboard | | Create App | `/apps/new` | New app wizard | | API Keys | `/settings/keys` | Manage API keys | | Signing Keys | `/settings/signing` | Manage signing keys | | Profile | `/settings/profile` | Account settings | --- ## Wireframes ### Dashboard ``` ┌─────────────────────────────────────────────────────────────┐ │ [Logo] Dashboard Apps Docs Settings [Avatar ▼] │ ├─────────────────────────────────────────────────────────────┤ │ │ │ Welcome back, Developer! │ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ Total Apps │ │ Downloads │ │ Active Users│ │ │ │ 12 │ │ 45,230 │ │ 1,234 │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ │ Your Apps [+ New App] │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ [Icon] My Calculator v1.2.0 Published 1.2K ↓ │ │ │ │ [Icon] Notes App v2.0.1 Published 5.4K ↓ │ │ │ │ [Icon] Weather Widget v0.9.0 In Review --- │ │ │ └──────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────┘ ``` ### App Details ``` ┌─────────────────────────────────────────────────────────────┐ │ ← Back to Apps │ ├─────────────────────────────────────────────────────────────┤ │ │ │ [Icon] My Calculator │ │ com.developer.calculator │ │ ● Published │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ Overview │ │ Versions │ │Analytics │ │ Settings │ │ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │ │ │ Latest Version: 1.2.0 [Submit New Version] │ │ Published: Jan 15, 2024 │ │ Downloads: 1,234 │ │ │ │ ┌────────────────────────────────────────┐ │ │ │ Downloads over time │ │ │ │ [Chart: line graph] │ │ │ └────────────────────────────────────────┘ │ │ │ │ Recent Crashes [View All →] │ │ • attempt to index nil (v1.2.0) - 23 reports │ │ • memory limit exceeded (v1.1.0) - 5 reports │ │ │ └─────────────────────────────────────────────────────────────┘ ``` ### Submit Version ``` ┌─────────────────────────────────────────────────────────────┐ │ Submit New Version - My Calculator │ ├─────────────────────────────────────────────────────────────┤ │ │ │ Step 2 of 3: Upload Package │ │ ○ Details ● Upload ○ Review │ │ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ │ │ │ │ ┌─────────┐ │ │ │ │ │ .mosis │ Drop your package here │ │ │ │ │ 📦 │ or click to browse │ │ │ │ └─────────┘ │ │ │ │ │ │ │ │ Max size: 50 MB │ │ │ │ │ │ │ └─────────────────────────────────────────────────────┘ │ │ │ │ ✓ Package validated │ │ ✓ Signature verified │ │ ✓ Permissions: storage, network │ │ │ │ [Back] [Continue to Review] │ │ │ └─────────────────────────────────────────────────────────────┘ ``` --- ## Tech Stack Options ### Option A: Next.js 14 ``` Framework: Next.js 14 (App Router) UI: shadcn/ui + Tailwind CSS State: React Query + Zustand Forms: React Hook Form + Zod Charts: Recharts or Tremor Auth: NextAuth.js ``` | Pros | Cons | |------|------| | SSR for SEO landing page | Complexity | | Great developer experience | React knowledge required | | Full-stack capability | Heavier bundle | | Large ecosystem | | ### Option B: SvelteKit ``` Framework: SvelteKit UI: Skeleton UI or custom State: Svelte stores Forms: Superforms Charts: Chart.js or LayerCake Auth: Lucia ``` | Pros | Cons | |------|------| | Fast, small bundles | Smaller ecosystem | | Simple state management | Fewer UI libraries | | Great DX | Less hiring pool | ### Option C: Astro + React Islands ``` Framework: Astro UI: React components (islands) State: Nanostores Forms: React Hook Form Charts: Recharts Auth: Custom ``` | Pros | Cons | |------|------| | Ultra-fast static pages | More setup | | Partial hydration | Newer approach | | Use React where needed | Less documented patterns | ### Option D: htmx + Go Templates ``` Framework: Go templates + htmx UI: Tailwind CSS State: Server-side Forms: Native HTML Charts: Chart.js Auth: Server sessions ``` | Pros | Cons | |------|------| | Simple, fast | Limited interactivity | | No JS framework | Less polished UX | | Server-rendered | Complex UI harder | --- ## UI Component Library ### Option A: shadcn/ui ``` Base: Radix UI primitives Styling: Tailwind CSS Approach: Copy-paste components ``` | Pros | Cons | |------|------| | High quality | React only | | Full control | Manual updates | | Accessible | | ### Option B: Tailwind UI ``` Base: Headless UI Styling: Tailwind CSS Approach: Copy-paste templates ``` | Pros | Cons | |------|------| | Beautiful designs | Paid ($299) | | Production-ready | Templates, not components | ### Option C: Mantine ``` Base: Custom components Styling: CSS-in-JS or CSS Approach: npm package ``` | Pros | Cons | |------|------| | Complete solution | Opinionated | | Many components | Larger bundle | | Good docs | | --- ## Key Features ### File Upload ```typescript // Drag and drop with progress

Drop your package here

 ``` ### Real-time Validation ```typescript // Validate package client-side before upload async function validatePackage(file: File) { const zip = await JSZip.loadAsync(file); // Check manifest const manifest = await zip.file('manifest.json')?.async('text'); if (!manifest) throw new Error('Missing manifest.json'); const parsed = JSON.parse(manifest); ManifestSchema.parse(parsed); // Check required files const entry = parsed.entry; if (!zip.file(entry)) { throw new Error(`Entry file not found: ${entry}`); } return parsed; } ``` ### Analytics Dashboard ```typescript // Recharts example ``` --- ## State Management ### Server State (React Query) ```typescript // Fetch apps const { data: apps, isLoading } = useQuery({ queryKey: ['apps'], queryFn: () => api.get('/apps'), }); // Create app mutation const createApp = useMutation({ mutationFn: (data) => api.post('/apps', data), onSuccess: () => { queryClient.invalidateQueries(['apps']); }, }); ``` ### Client State (Zustand) ```typescript // UI state const useStore = create((set) => ({ sidebarOpen: true, toggleSidebar: () => set((s) => ({ sidebarOpen: !s.sidebarOpen })), })); ``` --- ## Authentication Flow ### Login Page ```tsx export default function LoginPage() { return (

Sign in to Mosis
); } ``` ### Protected Routes ```tsx // Middleware (Next.js) export function middleware(request: NextRequest) { const token = request.cookies.get('token'); if (!token && request.nextUrl.pathname.startsWith('/dashboard')) { return NextResponse.redirect(new URL('/login', request.url)); } } ``` --- ## Responsive Design ### Breakpoints | Size | Width | Target | |------|-------|--------| | sm | 640px | Mobile landscape | | md | 768px | Tablet | | lg | 1024px | Desktop | | xl | 1280px | Large desktop | ### Mobile Navigation ```tsx // Hamburger menu for mobile ``` --- ## Accessibility ### Requirements - [ ] Keyboard navigation - [ ] Screen reader support - [ ] Color contrast (WCAG AA) - [ ] Focus indicators - [ ] Alt text for images - [ ] Form labels - [ ] Error announcements ### Testing ```bash # Lighthouse audit npx lighthouse http://localhost:3000 --view # axe-core npm install @axe-core/react ``` --- ## Deliverables - [ ] Framework selection - [ ] UI component library selection - [ ] Design system (colors, typography) - [ ] Page wireframes - [ ] Authentication flow - [ ] Dashboard implementation - [ ] App management pages - [ ] Version submission flow - [ ] Settings pages - [ ] Responsive design - [ ] Accessibility audit --- ## Open Questions 1. Dark mode support? 2. Internationalization (i18n)? 3. Custom domain for docs vs integrated? 4. Email notifications UI? --- ## References - [shadcn/ui](https://ui.shadcn.com/) - [Next.js App Router](https://nextjs.org/docs/app) - [Tailwind CSS](https://tailwindcss.com/) - [React Query](https://tanstack.com/query/latest)