> ## Documentation Index
> Fetch the complete documentation index at: https://docs.8space.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture Overview

> High-level architecture and design principles of 8Space

8Space is a modern project management platform built with a scalable, multi-tenant architecture. The system uses a monorepo structure with separate packages for the landing page and core application.

## Technology Stack

<CardGroup cols={2}>
  <Card title="Frontend" icon="react">
    * React 19 with TypeScript
    * Vite for build tooling
    * TanStack Query for state management
    * Radix UI component primitives
    * Tailwind CSS for styling
  </Card>

  <Card title="Backend" icon="database">
    * Supabase (PostgreSQL)
    * Row Level Security (RLS)
    * Database functions for complex operations
    * Real-time subscriptions
  </Card>

  <Card title="Landing Page" icon="globe">
    * Next.js 15 with App Router
    * React 19
    * MDX for content
    * Server-side rendering
  </Card>

  <Card title="Infrastructure" icon="server">
    * Monorepo with npm workspaces
    * Database migrations via Supabase CLI
    * Type-safe API layer
  </Card>
</CardGroup>

## Architectural Principles

### Repository Pattern

The application uses a repository pattern to abstract data access:

```typescript theme={null}
// packages/app/src/domain/repositories/interfaces.ts
export interface ProjectRepository {
  listProjects(userId: string, tenantSlug: string): Promise<Project[]>;
  createProjectWithDefaults(tenantSlug: string, input: CreateProjectInput): Promise<Project>;
  getProjectMembers(projectId: string): Promise<ProjectMember[]>;
  listWorkflowColumns(projectId: string): Promise<WorkflowColumn[]>;
  updateProjectSettings(projectId: string, input: Pick<Project, 'name' | 'description'>): Promise<Project>;
}
```

This pattern provides:

* Clear separation between business logic and data access
* Easy testing with mock implementations
* Single source of truth for data operations
* Type safety across the application

### Domain-Driven Design

Domain types are centralized in `packages/app/src/domain/types.ts`:

```typescript theme={null}
export interface Project {
  id: string;
  tenantId: string;
  name: string;
  description?: string | null;
  createdBy: string;
  createdAt: string;
  archivedAt?: string | null;
  role: ProjectRole;
}

export interface Task {
  id: string;
  projectId: string;
  title: string;
  statusColumnId: string;
  assignees: UserProfile[];
  dueDate?: string | null;
  startDate?: string | null;
  priority: TaskPriority;
  orderRank: number;
  description?: string | null;
  tags: TaskLabel[];
  checklist: TaskChecklistItem[];
  attachments: TaskAttachment[];
  estimate?: number | null;
  completedAt?: string | null;
  isMilestone: boolean;
  createdAt: string;
  updatedAt: string;
}
```

### Security-First Design

Security is enforced at the database level:

<Steps>
  <Step title="Row Level Security (RLS)">
    Every table has RLS enabled with policies controlling access
  </Step>

  <Step title="Security Definer Functions">
    Database functions run with elevated privileges but validate user permissions
  </Step>

  <Step title="Role-Based Access Control">
    Multi-level permissions: tenant roles and project roles
  </Step>

  <Step title="Authentication Context">
    All queries execute with `auth.uid()` context from Supabase Auth
  </Step>
</Steps>

## Key Features

### Multi-Tenancy

The platform supports multiple organizations (tenants) with isolated data:

* Each tenant has its own workspace with projects
* Projects belong to exactly one tenant
* Users can be members of multiple tenants
* Three-tier role hierarchy: tenant roles and project roles

[Learn more about multi-tenancy →](/architecture/multi-tenancy)

### Gantt Chart & Task Management

Comprehensive task management with dependencies:

* Kanban workflow columns (backlog, todo, in\_progress, done, custom)
* Task dependencies (Finish-to-Start)
* Task priorities (p0, p1, p2)
* Assignees, labels, checklists, attachments
* Milestones and estimates

### Real-Time Collaboration

Built on Supabase real-time infrastructure:

* Instant updates across connected clients
* Optimistic UI updates with background sync
* TanStack Query for caching and invalidation

## Performance Optimization

<AccordionGroup>
  <Accordion title="Database Indexing">
    Strategic indexes on frequently queried columns:

    ```sql theme={null}
    create index tasks_project_column_rank_idx on tasks (project_id, status_column_id, order_rank);
    create index tasks_project_due_date_idx on tasks (project_id, due_date);
    create index project_members_user_idx on project_members (user_id);
    create index tenant_members_user_idx on tenant_members (user_id);
    ```
  </Accordion>

  <Accordion title="Query Optimization">
    * Materialized views for dashboard metrics
    * Database functions for complex aggregations
    * Single-query data fetching with JOINs
  </Accordion>

  <Accordion title="Client-Side Caching">
    TanStack Query provides:

    * Automatic background refetching
    * Request deduplication
    * Optimistic updates
    * Stale-while-revalidate pattern
  </Accordion>
</AccordionGroup>

## Development Workflow

```bash theme={null}
# Start all services
npm run dev

# Start individual packages
npm run dev:app      # Main application (Vite)
npm run dev:landing  # Landing page (Next.js)

# Build for production
npm run build:app
npm run build:landing
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Monorepo Structure" icon="folder-tree" href="/architecture/monorepo-structure">
    Explore the folder structure and workspace organization
  </Card>

  <Card title="Database Schema" icon="database" href="/architecture/database-schema">
    Dive into the PostgreSQL schema and relationships
  </Card>

  <Card title="Multi-Tenancy" icon="users" href="/architecture/multi-tenancy">
    Understand the tenant isolation model
  </Card>

  <Card title="API Reference" icon="code" href="/api/overview">
    Browse the unified API documentation
  </Card>
</CardGroup>