QuillSpace

A high-performance, multi-tenant content management system built with Rust and modern web technologies.

🚀 One-Command Docker Deployment

Get QuillSpace running in seconds with full containerization:

./deploy-docker.sh

That's it! The script will:

• ✅ Build Docker images for frontend and backend
• ✅ Start PostgreSQL and ClickHouse containers
• ✅ Run database migrations automatically
• ✅ Deploy Rust backend in container
• ✅ Deploy Qwik frontend with Nginx
• ✅ Set up networking and health checks
• ✅ Provide complete production-ready stack

📱 Access Your Application

After deployment:

• Frontend: http://localhost (port 80)
• Backend API: http://localhost:3000
• Demo Login: [email protected] / admin123

🛠️ Prerequisites

• Docker & Docker Compose
• That's it! Everything else runs in containers.

📋 Docker Commands

Manage your containerized deployment:

# Deploy everything
./deploy-docker.sh

# View logs
docker-compose logs -f

# Stop all services
docker-compose down

# Restart services
docker-compose restart

# View service status
docker-compose ps

# Rebuild and restart
docker-compose up --build -d

🔧 Development Setup (Local)

For local development without Docker:

# Use the local deployment script
./deploy.sh

✨ Features

• Real-Time Analytics: Powered by ClickHouse for lightning-fast analytical queries
• Modern Frontend: Ultra-fast UI with Qwik's resumability architecture
• Scalable Design: Horizontal scaling with microservices architecture
• Type Safety: End-to-end type safety with Rust and TypeScript

🏗️ Architecture Overview

QuillSpace follows a modern microservices architecture optimized for multi-tenant SaaS applications:

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Qwik Frontend │────│  Axum API Layer │────│   PostgreSQL    │
│   (Resumable)   │    │   (Rust/Async)  │    │ (Transactional) │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                │
                                │
                       ┌─────────────────┐
                       │   ClickHouse    │
                       │   (Analytics)   │
                       └─────────────────┘

Technology Stack

Layer	Technology	Purpose
Frontend	Qwik + Qwik City	Ultra-fast resumable UI with O(1) JavaScript payload
Backend	Rust + Axum	High-performance async API with type safety
Database	PostgreSQL	ACID transactions, multi-tenant isolation
Analytics	ClickHouse	Real-time analytics and read models
Deployment	Docker + Kubernetes	Containerized microservices

📁 Project Structure

quillspace/
├── quillspace-core/          # Main Axum API server
│   ├── src/
│   │   ├── main.rs          # Application entry point
│   │   ├── routes/          # API route handlers
│   │   ├── models/          # Data models and schemas
│   │   ├── services/        # Business logic layer
│   │   └── middleware/      # Custom middleware
│   └── Cargo.toml
├── quilspace-lib/           # Shared library and utilities
│   ├── src/
│   │   ├── lib.rs          # Library entry point
│   │   ├── auth/           # Authentication utilities
│   │   ├── database/       # Database connections and queries
│   │   └── types/          # Shared type definitions
│   └── Cargo.toml
├── frontend/                # Qwik frontend application
│   ├── src/
│   │   ├── routes/         # Page routes
│   │   ├── components/     # Reusable UI components
│   │   └── services/       # API client services
│   └── package.json
├── docs/                    # Documentation
├── docker/                  # Docker configurations
└── k8s/                     # Kubernetes manifests

🚀 Quick Start

Prerequisites

• Rust 1.70+ with Cargo
• Node.js 18+ with npm/yarn
• Docker and Docker Compose
• PostgreSQL 15+
• ClickHouse 23+

Development Setup

1. Clone the repository:

   git clone <repository-url>
   cd quillspace

2. Start infrastructure services:

   docker-compose up -d postgres clickhouse

3. Run database migrations:

   cargo run --bin migrate

4. Start the backend server:

   cargo run --bin quillspace-core

5. Start the frontend development server:

   cd frontend
   npm install
   npm run dev

6. Access the application:

   • Frontend: http://localhost:5173
   • API: http://localhost:3000
   • API Docs: http://localhost:3000/docs

🔧 Development

Building the Project

# Build all workspace components
cargo build

# Build with optimizations
cargo build --release

# Build specific component
cargo build -p quillspace-core

Running Tests

# Run all tests
cargo test

# Run tests with coverage
cargo test --coverage

# Run integration tests
cargo test --test integration

Code Quality

# Format code
cargo fmt

# Run linter
cargo clippy

# Security audit
cargo audit

🏢 Multi-Tenant Features

QuillSpace is designed from the ground up for multi-tenancy:

• Row-Level Security: PostgreSQL RLS policies ensure data isolation
• Tenant-Scoped APIs: All endpoints automatically scope to tenant context
• Shared Infrastructure: Efficient resource utilization across tenants
• Tenant Analytics: ClickHouse provides isolated analytics per tenant
• Custom Branding: Per-tenant UI customization support

📊 Performance Characteristics

Based on the stack evaluation and implementation:

• API Throughput: 50,000+ requests/second with Axum (recommended over Poem/Salvo)
• Database: PostgreSQL with row-level security for multi-tenant isolation
• Analytics: ClickHouse delivers millisecond analytical queries vs minutes with traditional RDBMS
• Frontend: Qwik's resumability achieves ~90ms Time-to-Interactive vs 350ms for Next.js
• Memory Usage: ~10MB base memory footprint per Rust service
• Multi-Tenancy: Shared tables with tenant_id isolation supporting millions of tenants

🏗️ Implementation Highlights

This implementation follows the recommended architecture from the 2025 stack evaluation:

✅ Adopted Recommendations

• Axum over Poem/Salvo: Superior performance (6s vs slower alternatives for 1M requests)
• PostgreSQL over TypeDB: Proven multi-tenant isolation with RLS policies
• ClickHouse for Analytics: Shared-table strategy with row-level policies
• Comprehensive Middleware: Observability, security, and multi-tenancy built-in

🚀 Key Features Implemented

• Multi-Tenant Row-Level Security: PostgreSQL RLS with tenant_id isolation
• Real-Time Analytics: ClickHouse with materialized views and TTL policies
• Comprehensive Observability: Prometheus metrics, distributed tracing, structured logging
• Type-Safe API: End-to-end type safety with Rust and proper error handling
• Qwik Integration: Ultra-fast frontend with O(1) JavaScript payload sizes

🔐 Security

• Authentication: JWT-based with refresh tokens
• Authorization: Role-based access control (RBAC)
• Data Isolation: Tenant-scoped database queries
• API Security: Rate limiting, CORS, and request validation
• Audit Logging: Comprehensive audit trail for compliance

📚 Documentation

• Architecture Guide
• API Documentation
• Deployment Guide
• Development Setup
• Multi-Tenancy Guide

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

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

🙏 Acknowledgments

• Built with Axum - Modern Rust web framework
• Powered by Qwik - Resumable frontend framework
• Analytics by ClickHouse - Fast columnar database
• Generated with FerrisUp - Rust project templates