Skip to content

README.md

Latest commit

 

History

History
557 lines (437 loc) · 15.2 KB

README.md

File metadata and controls

557 lines (437 loc) · 15.2 KB

Katalyst - Spectrum Web Co AIO Management System

Katalyst Logo

The Complete All-in-One Management System for Modern Web Companies

A state-of-the-art React 19 framework powering marketing websites, consumer blogs, NFT storefronts, email management, admin dashboards, and content management systems.

Features • Quick Start • Architecture • Build System • Documentation

🌟 What is Katalyst?

Katalyst is Spectrum Web Co's comprehensive frontend solution that replaces the need for multiple separate systems. Think of it as WordPress for engineers - but built with modern React 19, TypeScript, and a unified build system.

Instead of cobbling together different tools and platforms, Katalyst provides everything you need in one cohesive system:

🎯 Core Applications

  • 🚀 Marketing Website (Next.js) - Static site generation with SEO optimization
  • 📝 Consumer Blog (Next.js + Payload CMS) - Content management with drag & drop editing
  • 🖼️ NFT Storefront (Next.js) - Complete marketplace for digital assets
  • 📧 Email Management (Core + Fly.io Backend) - Self-hosted email server interface
  • 📊 Admin Dashboard (Remix) - Comprehensive data management and analytics
  • ⚙️ Management Panel (Remix) - Storefront and content administration
  • 🌌 Metaverse Apps (WebXR) - Immersive VR/AR experiences across all platforms

🛠️ Technical Foundation

  • React 19 with concurrent features and modern patterns
  • 3 Meta Frameworks: Core (TanStack Router), Remix (Admin), Next.js (Marketing)
  • Unified Build System: Orchestrates Deno, Bun, NX, and Turborepo
  • TypeScript-First with strict type safety across the entire stack
  • Performance Optimized with multithreading, WebAssembly, and intelligent caching
  • Multi-Platform support for web, desktop (Tauri), mobile (RSpeedy), and VR/AR (WebXR)
  • Metaverse-Ready with spatial UI, hand tracking, and immersive 3D environments

✨ Features

🏢 Business Applications

  • Marketing Website: Modern, fast, SEO-optimized landing pages
  • Blog System: Drag & drop post creation with rich content editing
  • NFT Marketplace: Complete storefront with wallet integration
  • Email Platform: Self-hosted email management with custom apps
  • Analytics Dashboard: Real-time data visualization and insights
  • Content Management: Intuitive admin interface for all content

🔧 Developer Experience

  • Hot Reload: Instant development feedback across all frameworks
  • Type Safety: End-to-end TypeScript with strict checking
  • Component Library: Shared design system across all applications
  • Testing Suite: Comprehensive unit, integration, and E2E tests
  • Performance Monitoring: Built-in performance tracking and optimization
  • Cloud Caching: Intelligent build caching for 10-50x faster builds

🚀 Advanced Features

  • Multithreading: Web Workers for heavy computations
  • WebAssembly: Rust-powered performance optimizations
  • Web3 Integration: Built-in blockchain and crypto support
  • AI Integration: Advanced automation and intelligent features
  • Real-time Updates: Live data synchronization across applications
  • Progressive Enhancement: Works offline with service workers

🚀 Quick Start

Prerequisites

  • Deno 2.0+ (primary runtime)
  • Bun 1.0+ (fallback package manager)
  • Node.js 22.15+ (for compatibility)

1. Installation

# Clone the repository
git clone https://github.com/swcstudio/katalyst.git
cd katalyst

# Install dependencies (Deno primary, Bun fallback)
make install
# or
npm run install

2. Development

# Start all applications
make dev
# or
npm run dev

# Start specific applications
make dev-core      # Core application (port 20007)
make dev-remix     # Admin dashboard (port 20008)
make dev-nextjs    # Marketing website (port 20009)

3. Building

# Build all applications
make build
# or
npm run build

# Build for specific platforms
make build-web     # Web applications
make build-desktop # Desktop (Tauri)
make build-mobile  # Mobile (Tauri)

4. Testing

# Run all tests
make test
# or
npm test

# Specific test types
make test-unit         # Unit tests
make test-integration  # Integration tests
make test-e2e         # End-to-end tests
make test-performance # Performance benchmarks

🏗️ Architecture

Framework Structure

katalyst/
├── core/           # Main application (TanStack Router)
│   ├── Email Management Interface
│   ├── Real-time Dashboard
│   ├── Web3/AI Integration
│   └── Performance Optimizations
├── remix/          # Admin dashboard (Remix)
│   ├── Data Management
│   ├── Analytics Dashboard
│   ├── Content Administration
│   └── Storefront Management
├── next/           # Marketing website (Next.js)
│   ├── Static Site Generation
│   ├── Blog with Payload CMS
│   ├── NFT Storefront
│   └── SEO Optimization
└── shared/         # Common utilities
    ├── Components & Design System
    ├── Hooks & State Management
    ├── Types & Utilities
    └── Performance Tools

Technology Stack

🎯 Core Technologies

  • React 19 - Latest React with concurrent features
  • TypeScript 5.6 - Strict type safety
  • TanStack Router - Type-safe routing for Core app
  • Remix - Full-stack framework for admin features
  • Next.js 15 - Static generation for marketing
  • Payload CMS - Headless CMS for content management

⚡ Build & Performance

  • RSpack - Rust-powered bundler for maximum speed
  • Turborepo - Build pipeline optimization
  • NX - Intelligent monorepo management
  • Deno - Modern JavaScript runtime
  • Bun - Ultra-fast package manager

🎨 UI & Styling

  • Tailwind CSS 4.0 - Utility-first styling
  • Arco Design - Enterprise UI components
  • Framer Motion - Advanced animations
  • React Three Fiber - 3D graphics

🔧 Advanced Features

  • WebAssembly - Rust-powered computations
  • Web Workers - Multithreading support
  • Web3 Integration - Blockchain connectivity
  • AI Integration - Intelligent automation

🛠️ Build System

Katalyst uses a unified build orchestrator that intelligently manages multiple tools:

Tool Hierarchy

  1. Primary: Deno (package manager) + Turborepo (task runner)
  2. Fallback: Bun (package manager) + NX (task runner)
  3. Compatibility: npm/yarn for legacy support

Available Commands

📦 Package Management

make install                 # Install with Deno (fallback to Bun)
make install-fallback       # Force Bun installation
make install-force          # Clean reinstall
make update                 # Update dependencies

🚀 Development

make dev                    # All frameworks
make dev-core              # Core application only
make dev-remix             # Remix admin only
make dev-nextjs            # Next.js marketing only

🏗️ Building

make build                 # All frameworks (web)
make build-web            # Web platforms
make build-desktop        # Desktop applications
make build-mobile         # Mobile applications
make build-native         # Rust native components
make build-all            # All platforms

🧪 Testing

make test                 # All tests
make test-unit           # Unit tests
make test-integration    # Integration tests
make test-performance    # Performance tests
make test-e2e           # End-to-end tests
make test-coverage      # Coverage reports
make test-watch         # Watch mode

🔍 Code Quality

make lint               # Run linters
make lint-fix          # Fix linting issues
make typecheck         # TypeScript checking
make format            # Format code

🧹 Utilities

make clean             # Clean build artifacts
make clean-all         # Deep clean everything
make status            # System status
make doctor            # Comprehensive diagnostics
make cache-setup       # Setup cloud caching

Tool-Specific Commands

NX Commands

make nx-build          # Build using NX
make nx-test           # Test using NX
make nx-lint           # Lint using NX
make nx-reset          # Reset NX cache

Turbo Commands

make turbo-build       # Build using Turbo
make turbo-test        # Test using Turbo
make turbo-lint        # Lint using Turbo
make turbo-prune       # Prune Turbo cache

Bun Commands

make bun-install       # Install using Bun
make bun-build         # Build using Bun
make bun-test          # Test using Bun
make bun-dev           # Develop using Bun

Advanced Workflows

Parallel Execution

make parallel-test     # Run tests in parallel
make parallel-build    # Build frameworks in parallel

CI/CD Pipeline

make full-ci          # Complete CI workflow
make release-prep     # Prepare for release

Performance Optimization

make benchmark        # Run performance benchmarks
make cache-setup      # Enable cloud caching

📱 Applications

🎯 Core Application (Port 20007)

Purpose: Main application hub with advanced features

Features:

  • Email management interface for self-hosted server
  • Real-time dashboard with live updates
  • Web3 wallet integration and blockchain features
  • AI-powered automation and smart suggestions
  • Multithreading for heavy computations
  • WebAssembly for performance-critical operations

Tech Stack: React 19 + TanStack Router + RSpack

📊 Admin Dashboard (Port 20008)

Purpose: Comprehensive business management interface

Features:

  • Analytics and reporting dashboard
  • Content management for blog and storefront
  • User management and permissions
  • Data visualization and insights
  • Storefront product management
  • Email campaign management

Tech Stack: Remix + Server-side rendering + Database integration

🌐 Marketing Website (Port 20009)

Purpose: Public-facing marketing and content platform

Features:

  • Static site generation for performance
  • Blog with drag & drop post creation
  • NFT storefront with wallet connectivity
  • SEO optimization and meta tags
  • Contact forms and lead generation
  • Email subscription management

Tech Stack: Next.js 15 + Payload CMS + Static generation

🔧 Configuration

Environment Setup

# Copy environment template
cp .env.example .env

# Configure for development
make setup

Required Environment Variables

# Database
DATABASE_URL="your-database-url"

# Email Service (Fly.io)
EMAIL_SERVER_URL="your-email-server"
EMAIL_API_KEY="your-api-key"

# Authentication
CLERK_PUBLISHABLE_KEY="your-clerk-key"
CLERK_SECRET_KEY="your-clerk-secret"

# Cloud Caching
TURBO_TOKEN="your-turbo-token"
NX_CLOUD_ACCESS_TOKEN="your-nx-token"

# Deployment
VERCEL_TOKEN="your-vercel-token"
NETLIFY_AUTH_TOKEN="your-netlify-token"

Build Configuration

The build system is configured in build.config.ts with intelligent defaults for each framework and platform.

🚀 Deployment

Quick Deploy

# Deploy all applications
make deploy

# Deploy specific platforms
make deploy-web       # Web applications
make deploy-desktop   # Desktop applications
make deploy-mobile    # Mobile applications

Platform Support

  • Web: Vercel, Netlify, AWS S3
  • Desktop: Tauri (Windows, macOS, Linux)
  • Mobile: Tauri (iOS, Android)
  • Email Server: Fly.io backend integration

🧪 Testing

Test Suites

  • Unit Tests: Component and function testing
  • Integration Tests: Cross-framework functionality
  • E2E Tests: Complete user journeys
  • Performance Tests: Multithreading and WebAssembly benchmarks

Coverage Requirements

  • Statements: 80%
  • Branches: 80%
  • Functions: 80%
  • Lines: 80%

Running Tests

# Complete test suite
npm test

# With coverage
npm run test:coverage

# Watch mode for development
npm run test:watch

# CI/CD ready tests
npm run test:ci

📚 Documentation

Development Guides

Build System

Deployment

🤝 Contributing

Development Workflow

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Run tests: make test
  5. Submit a pull request

Code Standards

  • TypeScript: Strict mode enabled
  • Linting: Biome for formatting and linting
  • Testing: Comprehensive test coverage required
  • Documentation: Update docs for new features

Performance Requirements

  • Component render time < 16ms (60fps)
  • Bundle size < 500KB per framework
  • Test suite < 5 minutes execution time

📊 Performance

Benchmarks

  • Package Installation: Deno (0-5s) → Bun (5-15s) → npm (30-60s)
  • Build Time: Turbo cached (2-10s) → Turbo uncached (30-120s)
  • Test Execution: Deno (10-30s) → Traditional (30-90s)
  • Development Server: 3-8s startup time

Optimization Features

  • Cloud Caching: 10-50x build speedups
  • Parallel Execution: 2-4x improvement
  • Bundle Splitting: Optimized loading
  • Tree Shaking: Minimal bundle sizes

🔮 Roadmap

Immediate (Q1 2024)

  • Complete NFT storefront integration
  • Advanced email templates
  • Mobile app deployment
  • Performance optimizations

Short-term (Q2 2024)

  • AI-powered content generation
  • Advanced analytics dashboard
  • Multi-language support
  • Enhanced SEO tools

Long-term (Q3-Q4 2024)

  • Edge runtime support
  • Advanced Web3 features
  • Machine learning integration
  • Enterprise scaling

📝 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

👤 Author

SomeRandmGuyy

🙏 Acknowledgments

  • React team for React 19 and concurrent features
  • Deno team for the modern JavaScript runtime
  • Bun team for ultra-fast package management
  • Vercel team for Next.js and deployment platform
  • Remix team for the full-stack framework

📞 Support

Built with ❤️ for modern web development