System Architecture - Unified Space & Project

This document provides a comprehensive architectural overview of the unified space and project management system for AppFlowy. The system introduces a hierarchical space model with integrated project management capabilities.

Executive Summary

The unified space and project management system transforms AppFlowy's document organization by introducing:

Hierarchical space containers for documents and projects
Fine-grained role-based permissions at the space level
Integrated project management with kanban boards
Real-time collaboration with member management

System Architecture Overview

┌─────────────────────────────────────────────────────────────────────────────────┐
│                               AppFlowy Architecture                             │
│                                                                                 │
│  ┌─────────────────┐    ┌─────────────────┐    ┌───────────────────────────┐    │
│  │  Frontend (Web) │    │     Backend     │    │      Database Layer       │    │
│  │                 │    │                 │    │                           │    │
│  │ ┌─────────────┐ │    │ ┌─────────────┐ │    │ ┌─────────────────────┐   │    │
│  │ │Space Manager│ │◄───┤ │Space API    │ │◄───┤ │ af_space_members    │   │    │
│  │ └─────────────┘ │    │ └─────────────┘ │    │ └─────────────────────┘   │    │
│  │                 │    │                 │    │                           │    │
│  │ ┌─────────────┐ │    │ ┌─────────────┐ │    │ ┌─────────────────────┐   │    │
│  │ │Project View │ │◄───┤ │Project API  │ │◄───┤ │ af_project_metadata │   │    │
│  │ └─────────────┘ │    │ └─────────────┘ │    │ └─────────────────────┘   │    │
│  │                 │    │                 │    │                           │    │
│  │ ┌─────────────┐ │    │ ┌─────────────┐ │    │ ┌─────────────────────┐   │    │
│  │ │Member Panel │ │◄───┤ │Permission   │ │◄───┤ │ af_space_invitations│   │    │
│  │ └─────────────┘ │    │ │Service      │ │    │ └─────────────────────┘   │    │
│  │                 │    │ └─────────────┘ │    │                           │    │
│  └─────────────────┘    └─────────────────┘    └───────────────────────────┘    │
│                                                                                 │
│  ┌─────────────────────────────────────────────────────────────────────────┐    │
│  │                     Collaborative Layer                                 │    │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌──────────────┐    │    │
│  │  │Y.js Docs    │  │WebSocket    │  │Redis Cache  │  │Access Control│    │    │
│  │  └─────────────┘  └─────────────┘  └─────────────┘  └──────────────┘    │    │
│  └─────────────────────────────────────────────────────────────────────────┘    │
│                                                                                 │
└─────────────────────────────────────────────────────────────────────────────────┘

Data Model Architecture

Core Entities

Entity	Purpose	Key Relationships	Status
af_space_members	Member roles and permissions for spaces	→ af_workspace, af_user	✅ Implemented
af_space_invitations	Pending invitations to join spaces	→ af_workspace, af_user	✅ Implemented
af_project_metadata	Project-specific settings and stats	→ af_workspace	✅ Implemented
af_project_tasks	Tasks with document integration	→ af_project_metadata, af_user	✅ Implemented

Permission Model

Owner Role

All content permissions
Full member management
Space settings & deletion
Project: All task permissions

Admin Role

All content permissions
Member & role management
Space settings (no deletion)
Project: All task permissions

Editor Role

View, edit, create content
View members only
Project: Create & assign tasks
View reports

Viewer Role

View content only
View members only
Project: View reports only
No editing capabilities

API Architecture

RESTful Endpoints

POST

/api/spaces/{space_id}/members/invite

Invite new members to a space with specified role

GET

/api/spaces/{space_id}/members

List all space members with roles and user profiles

PUT

/api/spaces/{space_id}/members/{member_uid}

Update member role or permissions

DELETE

/api/spaces/{space_id}/members/{member_uid}

Remove member from space

GET

/api/spaces/{space_id}/permissions/{permission}

Check if user has specific permission in space

POST

/api/space-invitations/{token}/accept

Accept space invitation using invitation token

Technology Stack

Backend

Rust + Actix Web
PostgreSQL
SQLx ORM

Frontend

React + TypeScript
Tailwind CSS
React Query

Collaboration

Y.js Documents
WebSocket
Redis Cache

Database

PostgreSQL 15+
JSONB for settings
UUID primary keys

Implementation Phases

Phase 1: Backend Foundation

Status: ✅ Completed

Deliverables:

✅ Database schema with migrations
✅ Space member API endpoints
✅ Permission system with role-based access
✅ Integration with existing workspace system
✅ PostgreSQL functions for permission checking

Technical Implementation:

Created comprehensive database tables (af_space_members, af_space_invitations, af_project_metadata)
Implemented full REST API in Rust with proper error handling
Built permission service with caching and context awareness
Added proper indexes and constraints for performance

Phase 2: Frontend Space Management

Status: ✅ Completed

Delivered Components:

✅ Space settings UI with member management panel
✅ Member invitation flow with role selection
✅ Real-time member list with role editing
✅ Permission-based UI visibility controls
✅ Integration with existing workspace UI

Technical Implementation:

React components for member management
TypeScript interfaces matching backend API
React Query for API state management
Tailwind CSS for responsive design

Phase 3: Project Space Implementation

Status: ✅ Completed

Delivered Features:

✅ Project space type with kanban board
✅ Task management with drag & drop
✅ Task-to-document linking
✅ Project dashboard with analytics
✅ Project templates

Technical Components:

Kanban board using @dnd-kit library
Task persistence with database integration
Real-time updates with Y.js
Project analytics dashboard

Phase 4: Integration & Migration

Status: ✅ Completed

Delivered Capabilities:

✅ Migration tools for existing workspaces
✅ Space search and discovery
✅ Cross-space navigation
✅ Space templates and presets
✅ Space usage analytics

Migration Strategy:

Automatic migration for existing pages to spaces
Permission mapping from workspace to space level
Backward compatibility maintained
Progressive rollout capability

Key Technical Decisions

Architecture Patterns

Event-Driven Updates: Using WebSocket for real-time member changes
Permission Caching: Redis cache for permission checks
Optimistic UI: Frontend updates before server confirmation
Database Transactions: Ensuring data consistency for space operations

Security Considerations

Token-Based Invitations: Secure invitation links with expiration
Row-Level Security: PostgreSQL RLS for data isolation
Permission Inheritance: Space permissions cascade to content
Audit Logging: All permission changes are logged

Performance Optimizations

Lazy Loading: Load space members on demand
Batch Operations: Bulk invite and permission updates
Index Strategy: Optimized indexes for permission queries
Connection Pooling: Efficient database connection management

Future Enhancements

Planned Features

External Sharing: Share spaces with external users
Space Analytics: Advanced usage and activity metrics
Custom Roles: Define custom permission sets
Space Archiving: Archive inactive spaces
API Access: Third-party integration support

Monitoring & Metrics

Key Performance Indicators

Space creation rate
Member invitation acceptance rate
Average members per space
Permission check latency
API response times

Health Metrics

Database connection pool usage
Redis cache hit rate
WebSocket connection stability
Error rates by endpoint