hosting-frontend/openspec/project.md

Project Context

Purpose

This is a Portfolio Hosting Management Platform - a SaaS application that enables users to create, upload, deploy, and manage their portfolio websites with custom domains. Users can register for accounts, upload portfolio content as ZIP files, and deploy them to custom domains with automated hosting infrastructure.

Primary Goals

• Provide a simple, user-friendly interface for portfolio deployment
• Enable non-technical users to host professional portfolio websites
• Support multiple portfolios per user with custom domain mapping
• Offer seamless file upload and deployment workflows
• Display public portfolio examples to attract new users

Tech Stack

Current Stack (Angular - To Be Migrated)

• Frontend Framework: Angular 20 (standalone components)
• Language: TypeScript 5.8.2
• Styling: Tailwind CSS 4.1.8
• State Management: RxJS 7.8.0 (BehaviorSubjects)
• Forms: Angular Reactive Forms
• HTTP Client: Angular HttpClient with interceptors
• Routing: Angular Router
• Testing: Jasmine 5.7.0 + Karma 6.4.0
• Build Tool: Angular CLI 20.0.0
• Package Manager: npm

Target Stack (Next.js - Migration in Progress)

• Frontend Framework: Next.js 15 (App Router)
• UI Component Library: Launch UI (shadcn/ui + Tailwind CSS 4.0)
• Language: TypeScript 5.0
• Styling: Tailwind CSS 4.0
• State Management: React Context API + hooks
• Forms: React Hook Form
• HTTP Client: Native fetch with custom wrapper
• Icons: Lucide React
• Testing: Jest + React Testing Library
• Build Tool: Next.js + Turbopack
• Package Manager: npm

Backend (Unchanged)

• API Server: Separate backend service (not part of this repository)
• Authentication: JWT Bearer tokens
• API Base URL:
  • Development: http://localhost:8000/api
  • Production: https://api.portfolio-host.com/api

Infrastructure

• Containerization: Docker (Dockerfile in repository)
• Deployment: Kubernetes with Ingress
• Version Control: Git (current branch: main)

Project Conventions

Code Style

TypeScript

• Strict Mode: Enabled (strict: true in tsconfig.json)
• Null Checks: Enforced (strictNullChecks: true)
• Explicit Types: Required (noImplicitAny: true)
• Target: ES2022

Naming Conventions

• Files: kebab-case (e.g., api-client.ts, auth-provider.tsx)
• Components: PascalCase (e.g., LoginComponent, DashboardPage)
• Functions/Variables: camelCase (e.g., getUserData, isAuthenticated)
• Constants: UPPER_SNAKE_CASE (e.g., API_BASE_URL, MAX_FILE_SIZE)
• Interfaces/Types: PascalCase with descriptive names (e.g., Portfolio, ApiResponse<T>)

Code Organization (Next.js Target)

• Components: /components directory, grouped by feature or UI library
  • /components/launch-ui/ - Launch UI components
  • /components/ui/ - shadcn/ui primitives
  • /components/auth/ - Authentication-related components
• Pages: /app directory using App Router conventions
• Utilities: /lib directory for shared utilities and API client
• Hooks: /hooks directory for custom React hooks
• Types: /lib/types.ts or co-located with features

Formatting

• Indentation: 2 spaces (no tabs)
• Quotes: Single quotes for strings (except JSX attributes use double quotes)
• Semicolons: Required
• Line Length: 100 characters (soft limit)
• Trailing Commas: Yes (for multi-line arrays/objects)

Architecture Patterns

Component Architecture (Next.js)

• React Server Components (RSC): Default for pages and non-interactive components
• Client Components: Explicitly marked with 'use client' directive
• Composition Over Inheritance: Prefer component composition
• Single Responsibility: Each component has one clear purpose

State Management

• Global State: React Context API for authentication and user data
• Local State: useState for component-level state
• Server State: useEffect + fetch for data fetching (consider SWR/React Query for future enhancement)
• Form State: React Hook Form for all forms

API Integration

• API Client Pattern: Centralized fetch wrapper in /lib/api-client.ts
• Generic Methods: Typed request methods (get<T>, post<T>, etc.)
• Error Handling: Centralized error handling with automatic 401 logout
• Authentication: Bearer token injection via function wrapper (not middleware in fetch)
• Response Model: All API responses follow ApiResponse<T> interface

Routing Strategy

• File-Based Routing: Next.js App Router (/app directory)
• Protected Routes: Middleware-based authentication check
• Layouts: Shared layouts in layout.tsx files
• Metadata: Page-level SEO metadata using Next.js metadata API

Styling Strategy

• Utility-First CSS: Tailwind CSS utilities for all styling
• Component Variants: shadcn/ui variant patterns (e.g., variant="outline")
• Responsive Design: Mobile-first breakpoints (sm, md, lg, xl, 2xl)
• Custom Themes: Extend Tailwind config for brand colors and typography
• CSS Modules: Avoid - prefer Tailwind utilities

Testing Strategy

Current (Angular - To Be Replaced)

• Unit Tests: Jasmine + Karma for component and service tests
• Test Location: *.spec.ts files co-located with source files
• Coverage Target: Not formally defined

Target (Next.js)

• Unit Tests: Jest + React Testing Library
• Component Tests: Test user interactions and rendering
• Integration Tests: Test authentication flows and API interactions
• E2E Tests: (Future) Playwright or Cypress for critical user journeys
• Test Location: *.test.tsx or __tests__/ directories
• Coverage Target: 70%+ for critical paths (auth, API client)
• Accessibility Tests: axe-core integration for WCAG 2.1 AA compliance

Testing Principles

• Test user behavior, not implementation details
• Mock external API calls in unit tests
• Use integration tests for authentication flow validation
• Validate form validation logic thoroughly
• Test error states and edge cases

Git Workflow

Branching Strategy

• Main Branch: main (production-ready code)
• Feature Branches: feature/<feature-name> (e.g., feature/nextjs-migration)
• Bugfix Branches: fix/<bug-description> (e.g., fix/login-redirect)
• Hotfix Branches: hotfix/<issue> for production issues

Commit Conventions

• Format: <type>(<scope>): <subject>
• Types:
  • feat: New feature
  • fix: Bug fix
  • refactor: Code refactoring
  • docs: Documentation changes
  • style: Formatting changes
  • test: Adding or updating tests
  • chore: Build tasks, dependencies

Examples:

• feat(auth): implement JWT token refresh
• fix(dashboard): correct portfolio status badge logic
• refactor(api): migrate from Angular HttpClient to fetch

Pull Request Process

• Create PR with descriptive title and summary
• Link related issues or OpenSpec changes
• Request code review from at least one team member
• Ensure CI/CD checks pass (tests, linting, build)
• Squash commits before merging to main

Domain Context

Core Domain Concepts

Portfolio

A user's website project that can be uploaded, deployed, and hosted.

• Status States:
  • Inactive - Payment pending (not active)
  • Pending Upload - Active but no files uploaded (no path)
  • Uploaded - Files uploaded, ready for deployment (has path)
• Deployment: Portfolio ZIP files are extracted and served at custom domains
• Domain Mapping: Each portfolio has a unique domain (user-defined)

User Authentication

• Registration: Users provide name, email, and password
• Login: Email/password authentication returns JWT token
• Session Management: JWT tokens stored in localStorage, included in API requests
• Token Refresh: Backend supports token refresh endpoint

File Upload

• Format: ZIP files containing portfolio HTML/CSS/JS
• Process: Upload → Extract → Deploy to domain
• Size Limits: (Backend-defined, not enforced in frontend)

User Roles

Currently single-role system:

• Authenticated User: Can create, upload, and manage their own portfolios

Key User Flows

1. New User Registration

   • User visits landing page
   • Clicks "Sign Up" → Registration form
   • Submits name, email, password → Backend creates account
   • Redirects to login page

2. Existing User Login

   • User navigates to /login
   • Submits email + password
   • Receives JWT token → Stored in localStorage
   • Redirects to dashboard

3. Portfolio Creation & Deployment

   • User creates new portfolio (name + domain)
   • Uploads ZIP file → Backend processes
   • Clicks "Deploy" → Portfolio goes live at custom domain
   • Visits domain to view live portfolio

4. Portfolio Example Discovery

   • Visitor on landing page clicks "View Example"
   • Random portfolio fetched from API
   • Redirects to example portfolio domain

Important Constraints

Technical Constraints

• API Compatibility: Frontend must remain compatible with existing backend API (no backend changes allowed during migration)
• JWT Token Format: Must preserve existing JWT authentication pattern
• Bundle Size: Next.js production bundle should be ≤500KB (main JS)
• Browser Support: Modern browsers (Chrome, Firefox, Safari, Edge - latest 2 versions)
• TypeScript Version: Next.js migration requires TypeScript 5.0 (downgrade from 5.8)
• Mobile Responsiveness: Must support viewports down to 375px width

Business Constraints

• Zero Downtime Deployment: Migration must not cause service interruption
• Session Preservation: Minimize user re-authentication during migration (stretch goal)
• Feature Parity: All Angular features must be replicated in Next.js version before cutover
• Performance Requirements: Core Web Vitals must meet or exceed current benchmarks
  • First Contentful Paint (FCP): <1.0s
  • Largest Contentful Paint (LCP): <1.5s
  • Time to Interactive (TTI): <2.0s

Design Constraints

• UI Library: Launch UI (free version) must be used for landing page components
• Accessibility: WCAG 2.1 Level AA compliance required
• SEO: Server-side rendering required for public pages (landing, login, register)

Infrastructure Constraints

• Deployment Platform: Must remain Docker-based (Dockerfile required)
• Environment Variables: Must support development and production configurations
• Reverse Proxy: Deployment assumes reverse proxy/Ingress for routing

External Dependencies

APIs

• Backend API: RESTful API for authentication and portfolio management
  • Base URL: {environment.apiUrl}/api
  • Endpoints: /auth/*, /portfolios/*, /portfolio/random
  • Authentication: Bearer token (JWT)
  • Response Format: { success: boolean, data?: T, message?: string, errors?: any }

Third-Party Libraries

• Launch UI: Open-source UI component library (MIT license)
  • Repository: https://github.com/launch-ui/launch-ui
  • Components: Navbar, Hero, Items, Logos, FAQ, Stats, CTA, Footer
  • Foundation: shadcn/ui + Tailwind CSS
• shadcn/ui: Headless component library (copy-paste components)
• Lucide Icons: Icon library (MIT license)
• Tailwind CSS: Utility-first CSS framework (MIT license)

Build & Development Tools

• Next.js: React framework (MIT license)
• TypeScript: JavaScript superset (Apache 2.0)
• PostCSS: CSS processing (MIT license)
• Autoprefixer: CSS vendor prefixing (MIT license)

Testing & Quality Tools

• Jest: Testing framework (MIT license)
• React Testing Library: Component testing (MIT license)
• axe-core: Accessibility testing (Mozilla Public License 2.0)

Migration Notes

Current Status

• Phase: Planning and proposal stage (OpenSpec change in progress)
• Change ID: migrate-to-nextjs-launchui
• Affected Capabilities: frontend, ui-components, authentication, routing, state-management

Key Decisions

1. Next.js App Router over Pages Router (future-proof, Launch UI compatibility)
2. React Hook Form for form management (performance, TypeScript support)
3. React Context API for state (simplicity, adequate for scale)
4. Native fetch with custom wrapper (Next.js optimization, smaller bundle)
5. Parallel deployment strategy (risk mitigation, gradual rollout)

Post-Migration Conventions

Once migration is complete, this section will be removed and the conventions above will reflect the Next.js stack as the primary architecture.