Project Overview: Constellation Front-end
Project Vision & Goals
Constellation is a comprehensive web application platform designed to provide users with collaborative workspace tools, rich content editing capabilities, and visual data representation. The front-end application serves as the primary user interface for interacting with the Constellation ecosystem.
Core Objectives
- Provide a Seamless Collaborative Experience - Users can work together in real-time with synchronized data
- Enable Rich Content Creation - Advanced text editing with media, formatting, and embedding capabilities
- Visualize Complex Data - Interactive graphs and mapping tools for data exploration
- Support Multi-tenant Architecture - Isolated workspaces and admin controls
- Ensure Accessibility & Performance - Fast, responsive, and accessible to all users
- Enable Global Reach - Multi-language support from day one
Architecture Overview
Frontend Stack
┌─────────────────────────────────────────────┐
│ Constellation Front-end │
├─────────────────────────────────────────────┤
│ Next.js 15 (React 19) │
│ ├─ App Router │
│ ├─ API Routes │
│ └─ Image Optimization │
├─────────────────────────────────────────────┤
│ Components & Hooks │
│ ├─ Shadcn/ui Components │
│ ├─ Custom React Components │
│ ├─ Custom Hooks │
│ └─ Context Providers │
├─────────────────────────────────────────────┤
│ Features │
│ ├─ Rich Text Editor (Plate.js) │
│ ├─ Workspace Management │
│ ├─ Dashboard & Analytics │
│ ├─ Admin Panel │
│ └─ Homepage & Marketing │
├─────────────────────────────────────────────┤
│ Services & Utilities │
│ ├─ API Client │
│ ├─ Authentication │
│ ├─ i18n (Internationalization) │
│ ├─ Form Validation (Zod) │
│ └─ Utilities & Helpers │
├─────────────────────────────────────────────┤
│ Styling & Design │
│ ├─ Tailwind CSS │
│ ├─ PostCSS │
│ └─ Component Theme System │
├─────────────────────────────────────────────┤
│ Testing & Quality │
│ ├─ Vitest │
│ ├─ Testing Library │
│ ├─ MSW (Mock Service Worker) │
│ └─ ESLint │
└─────────────────────────────────────────────┘
Microservices Integration
The front-end communicates with multiple backend services:
Constellation Front-end
├─ Neo4j API (Graph Database)
│ └─ localhost:8000
├─ Main API (Core Business Logic)
│ └─ localhost:8001
├─ SSE Service (Real-time Events)
│ └─ localhost:8002
├─ Hocuspocus (CRDT Sync)
│ └─ ws://localhost:8003
└─ AI API (AI/ML Features)
└─ localhost:8004
Key Features
1. Rich Text Editor
- Engine: Plate.js (Slate-based)
- Capabilities:
- Block editing with multiple node types
- Formatting (bold, italic, underline, code)
- Lists, tables, code blocks
- Media embedding (images, videos)
- Mentions, emojis, slash commands
- Comments and collaborative editing
- Location: src/components/editor
2. Workspace Management
- Multi-workspace Support: Users can create and manage multiple workspaces
- Real-time Collaboration: Synchronized edits across team members
- Permissions: Role-based access control (admin, editor, viewer)
- Location: src/features/workspace
3. Dashboard & Analytics
- User Dashboard: Personal workspace overview
- Analytics: Project statistics and usage metrics
- Graph Visualization: Interactive network and data visualization
- Location: src/components/dashboard
4. Admin Panel
- User Management: Create, edit, delete users
- Content Moderation: Review and manage user content
- System Settings: Configure application behavior
- Location: src/components/admin
5. Authentication & Authorization
- OAuth Integration: Google OAuth support
- Session Management: Secure token handling
- Role-based Access: Admin, workspace owner, member roles
- Location: src/lib/auth.ts
6. Internationalization
- Supported Languages: English, French
- Dynamic Language Switching: Change language on-the-fly
- Translation Management: i18n configuration
- Location: src/i18n
Project Structure
constellation/
├── src/
│ ├── app/ # Next.js App Router pages
│ │ ├── (admin)/ # Admin-protected routes
│ │ ├── (www)/ # Public routes
│ │ ├── api/ # API routes
│ │ ├── dashboard/ # User dashboard
│ │ └── workspace/ # Workspace pages
│ │
│ ├── components/ # Reusable React components
│ │ ├── admin/ # Admin-specific components
│ │ ├── common/ # Shared components
│ │ ├── context/ # Context providers
│ │ ├── dashboard/ # Dashboard components
│ │ ├── editor/ # Editor components (Plate.js)
│ │ ├── forms/ # Form components
│ │ ├── graph/ # Graph visualization
│ │ ├── mapEditor/ # Map editor components
│ │ ├── navigation/ # Navigation components
│ │ ├── plate-ui/ # Plate.js UI components
│ │ └── ui/ # Shadcn/ui components
│ │
│ ├── features/ # Feature-level logic
│ │ ├── homepage/ # Homepage feature
│ │ └── workspace/ # Workspace feature
│ │
│ ├── hooks/ # Custom React hooks
│ │ ├── use-admin-ping.tsx
│ │ ├── use-copy-to-clipboard.tsx
│ │ ├── use-custom-chat.tsx
│ │ ├── use-debounce.ts
│ │ ├── use-is-admin.tsx
│ │ ├── use-mobile.tsx
│ │ ├── use-mounted.tsx
│ │ ├── use-yjs.tsx
│ │ └── ...
│ │
│ ├── i18n/ # Internationalization
│ │ └── i18n.js
│ │
│ ├── lib/ # Utilities and libraries
│ │ ├── auth.ts
│ │ ├── api.ts # API client
│ │ ├── utils.ts
│ │ ├── schemas/ # Zod validation schemas
│ │ └── ...
│ │
│ ├── services/ # API services
│ │ ├── apiClient.ts
│ │ ├── token.ts
│ │ └── admin/
│ │
│ ├── types/ # TypeScript type definitions
│ │ ├── chat.ts
│ │ ├── data.ts
│ │ └── ...
│ │
│ ├── test/ # Test utilities and setup
│ │ ├── mocks/
│ │ │ ├── server.ts
│ │ │ └── handlers.ts
│ │ └── test-utils.tsx
│ │
│ ├── app.css # Global styles
│ ├── layout.tsx # Root layout
│ └── page.tsx # Root page
│
├── public/ # Static assets
│ ├── fonts/
│ ├── images/
│ ├── locales/ # i18n JSON files
│ └── logos/
│
├── docs/ # Documentation (this folder)
├── coverage/ # Test coverage reports
├── build/ # Build output
│
├── tailwind.config.ts # Tailwind configuration
├── tsconfig.json # TypeScript configuration
├── next.config.mjs # Next.js configuration
├── eslint.config.mjs # ESLint configuration
├── vitest.config.ts # Vitest configuration
├── package.json # Dependencies and scripts
└── README.md # Project README
Development Workflow
1. Feature Development
1. Create feature branch
2. Implement feature in src/
3. Write tests
4. Run linter
5. Create pull request
6. Code review
7. Merge to main
8. Deploy
2. Code Organization
- Components - Pure presentation logic
- Hooks - Reusable state and side effects
- Services - API communication
- Utils - Helper functions
- Types - TypeScript definitions
3. Testing Strategy
- Unit Tests - Test individual functions and hooks
- Component Tests - Test component rendering and interaction
- Integration Tests - Test feature workflows
- E2E Tests - Test complete user journeys (future)
Performance Considerations
Optimization Strategies
- Code Splitting - Next.js automatic route-based splitting
- Image Optimization - Next.js Image component
- Component Lazy Loading - React.lazy for heavy components
- Memoization - React.memo for expensive renders
- Server-side Rendering - Next.js SSR for fast initial load
- Static Generation - Pre-render static pages
Monitoring
- Bundle Size - Monitor with
@next/bundle-analyzer - Performance Metrics - Core Web Vitals tracking
- Error Tracking - Integration with error monitoring service
- User Analytics - Hotjar integration
Deployment Pipeline
Development Branch
↓
Feature Branch + PR
↓
Code Review + Tests
↓
Merge to Main
↓
Build Process
↓
Staging Environment
↓
Production Deployment
See DEPLOYMENT.md for detailed deployment instructions.
Related Documentation
- 📐 ARCHITECTURE.md - Deep dive into system design
- 🔧 SETUP_GUIDE.md - Environment setup
- 🚀 QUICK_START.md - Get started in 10 minutes
- 📚 COMPONENTS.md - Component library
Glossary
| Term | Definition |
|---|---|
| SSR | Server-Side Rendering - rendering React on the server |
| CRDT | Conflict-free Replicated Data Type - for collaborative editing |
| i18n | Internationalization - multi-language support |
| RBAC | Role-Based Access Control - permission system |
| MSW | Mock Service Worker - API mocking for tests |
| Zod | TypeScript-first schema validation library |
Last Updated: January 2026
Maintained By: Constellation Team