Quality Attributes

apps/
├── web/          // Main Next.js platform (port 7803) - workspace management
├── tanstack-web/ // TanStack Start successor to apps/web (migration in progress)
├── backend/      // Rust backend (port 7820)
├── finance/      // Finance surface
├── calendar/     // Calendar surface
├── tasks/        // Tasks surface
├── nova/         // AI challenges
├── rewise/       // AI chat
└── mobile/       // Flutter mobile app

// Each app owns a focused surface. The web-facing apps are conventional
// Next.js App Router apps; they share one Supabase project rather than
// each owning a private datastore. Cross-cutting product logic lives in
// shared packages (packages/internal-api, packages/types, packages/ui).

// apps/web/src/app/[locale]/(dashboard)/[wsId]/
finance/
├── layout.tsx              // Finance-specific layout
├── transactions/           // Transaction management
├── reports/                // Financial reports
└── settings/               // Finance settings

// Finance module is self-contained
// Changes here don't affect calendar or tasks modules

// Illustrative: business logic expressed against an interface, not an implementation
export interface WorkspaceRepository {
  findById(id: string): Promise<Workspace | null>;
  save(workspace: Workspace): Promise<void>;
  delete(id: string): Promise<void>;
}

// Core business logic depends on the interface
export class WorkspaceService {
  constructor(private repo: WorkspaceRepository) {}

  async archiveWorkspace(id: string) {
    const workspace = await this.repo.findById(id);
    if (!workspace) throw new Error('Workspace not found');

    workspace.archive(); // Pure business logic
    await this.repo.save(workspace);
  }
}

// Illustrative infrastructure implementation (the swappable seam)
export class SupabaseWorkspaceRepository implements WorkspaceRepository {
  constructor(private client: SupabaseClient) {}

  async findById(id: string) {
    const { data } = await this.client
      .from('workspaces')
      .select('*')
      .eq('id', id)
      .single();

    return data ? this.toDomain(data) : null;
  }

  async save(workspace: Workspace) {
    await this.client
      .from('workspaces')
      .upsert(this.toDatabase(workspace));
  }

  async delete(id: string) {
    await this.client
      .from('workspaces')
      .delete()
      .eq('id', id);
  }
}

// Future: Can swap Supabase for Prisma, Drizzle, or any other ORM
// WITHOUT changing business logic

// Today: Supabase
const repo = new SupabaseWorkspaceRepository(supabaseClient);

// Tomorrow: Drizzle ORM (business logic unchanged)
const repo = new DrizzleWorkspaceRepository(drizzleClient);

// Next year: Different database (business logic still unchanged)
const repo = new MongoWorkspaceRepository(mongoClient);

// Business logic stays the same:
const service = new WorkspaceService(repo);
await service.archiveWorkspace('ws-123');

// Illustrative domain core (unchanged when infrastructure changes)
export class TaskService {
  constructor(
    private taskRepo: TaskRepository,
    private eventBus: EventBus,
    private logger: Logger
  ) {}

  async createTask(data: CreateTaskData) {
    const task = Task.create(data);

    await this.taskRepo.save(task);
    await this.eventBus.publish(new TaskCreated(task));
    this.logger.info('Task created', { taskId: task.id });

    return task;
  }
}

// Infrastructure layer (changeable without affecting domain)
// Version 1: Supabase + Trigger.dev + Console logging
const service = new TaskService(
  new SupabaseTaskRepository(supabase),
  new TriggerEventBus(trigger),
  new ConsoleLogger()
);

// Version 2: Drizzle + NATS + Structured logging
// Domain core completely unchanged!
const service = new TaskService(
  new DrizzleTaskRepository(drizzle),
  new NatsEventBus(nats),
  new StructuredLogger(winston)
);

// Business logic and components remain the same
// Only infrastructure adapters need updates

// Before Next.js 16
export function getWorkspaceData(id: string) {
  // Implementation using Next.js 15 patterns
}

// After Next.js 16
export function getWorkspaceData(id: string) {
  // Implementation using Next.js 16 patterns
  // Component code using this function unchanged
}

apps/web/src/
├── app/[locale]/(dashboard)/[wsId]/
│   ├── finance/                    // Finance module
│   │   ├── layout.tsx
│   │   ├── transactions/
│   │   ├── reports/
│   │   └── _components/           // Finance-specific components
│   ├── calendar/                   // Calendar module
│   │   ├── layout.tsx
│   │   ├── events/
│   │   └── _components/           // Calendar-specific components
│   └── tasks/                      // Tasks module
│       ├── layout.tsx
│       ├── boards/
│       └── _components/           // Task-specific components
├── components/
│   ├── finance/                   // Shared finance components
│   ├── calendar/                  // Shared calendar components
│   ├── tasks/                     // Shared task components
│   └── common/                    // Truly shared components

// Finance module - self-contained state management
// apps/web/src/app/[locale]/(dashboard)/[wsId]/finance/state.ts
import { atom } from 'jotai';

export const financeTransactionsAtom = atom<Transaction[]>([]);
export const financeFiltersAtom = atom<Filters>({});

// Calendar module - separate state management
// apps/web/src/app/[locale]/(dashboard)/[wsId]/calendar/state.ts
import { atom } from 'jotai';

export const calendarEventsAtom = atom<Event[]>([]);
export const calendarViewAtom = atom<'month' | 'week' | 'day'>('month');

// Modules don't share state - clear boundaries

# Build a single workspace and its dependency graph (Turborepo filters by app)
bun turbo run build --filter=@tuturuuu/web

# Run an app locally (each app owns its own dev script)
cd apps/finance && bun dev

# Real per-app preview workflow — .github/workflows/vercel-preview-finance.yaml
name: Vercel Finance Preview Deployment
# Builds only the shared deps the finance app needs, then deploys it to Vercel:
#   bun turbo:local run build --filter=@tuturuuu/types --filter=@tuturuuu/supabase --filter=@tuturuuu/internal-api

// Illustrative pure logic — no I/O, fully testable
export class Workspace {
  private constructor(
    public readonly id: string,
    public name: string,
    public status: 'active' | 'archived',
    public memberLimit: number
  ) {}

  static create(data: CreateWorkspaceData): Workspace {
    if (data.name.length < 3) {
      throw new Error('Workspace name must be at least 3 characters');
    }

    return new Workspace(
      uuid(),
      data.name,
      'active',
      data.memberLimit || 10
    );
  }

  archive() {
    if (this.status === 'archived') {
      throw new Error('Workspace already archived');
    }
    this.status = 'archived';
  }

  addMember() {
    // Business rule: enforce member limit
    if (this.getMemberCount() >= this.memberLimit) {
      throw new Error('Member limit reached');
    }
    // ... add member logic
  }
}

// Test - no infrastructure required (Vitest, colocated *.test.ts)
describe('Workspace', () => {
  describe('create', () => {
    it('creates workspace with valid name', () => {
      const workspace = Workspace.create({
        name: 'My Workspace',
        memberLimit: 10
      });

      expect(workspace.name).toBe('My Workspace');
      expect(workspace.status).toBe('active');
      expect(workspace.memberLimit).toBe(10);
    });

    it('rejects workspace with short name', () => {
      expect(() => {
        Workspace.create({ name: 'ab', memberLimit: 10 });
      }).toThrow('Workspace name must be at least 3 characters');
    });
  });

  describe('archive', () => {
    it('archives active workspace', () => {
      const workspace = Workspace.create({ name: 'Test', memberLimit: 10 });

      workspace.archive();

      expect(workspace.status).toBe('archived');
    });

    it('rejects archiving already archived workspace', () => {
      const workspace = Workspace.create({ name: 'Test', memberLimit: 10 });
      workspace.archive();

      expect(() => workspace.archive()).toThrow('Workspace already archived');
    });
  });
});

// Tests run in <1ms each, no database required

// Illustrative interface seam
export interface TaskRepository {
  findById(id: string): Promise<Task | null>;
  save(task: Task): Promise<void>;
  findByWorkspace(workspaceId: string): Promise<Task[]>;
}

// Production implementation (Supabase)
export class SupabaseTaskRepository implements TaskRepository {
  // ... real database implementation
}

// Test implementation (in-memory)
export class InMemoryTaskRepository implements TaskRepository {
  private tasks = new Map<string, Task>();

  async findById(id: string): Promise<Task | null> {
    return this.tasks.get(id) || null;
  }

  async save(task: Task): Promise<void> {
    this.tasks.set(task.id, task);
  }

  async findByWorkspace(workspaceId: string): Promise<Task[]> {
    return Array.from(this.tasks.values())
      .filter(task => task.workspaceId === workspaceId);
  }

  // Test helpers
  clear() {
    this.tasks.clear();
  }

  count() {
    return this.tasks.size;
  }
}

// Test using in-memory repository
describe('TaskService', () => {
  let taskRepo: InMemoryTaskRepository;
  let service: TaskService;

  beforeEach(() => {
    taskRepo = new InMemoryTaskRepository();
    service = new TaskService(taskRepo);
  });

  it('creates task', async () => {
    const task = await service.createTask({
      title: 'Test task',
      workspaceId: 'ws-123'
    });

    expect(task.title).toBe('Test task');
    expect(taskRepo.count()).toBe(1);

    // Verify task was saved
    const saved = await taskRepo.findById(task.id);
    expect(saved).toBeDefined();
  });

  it('finds tasks by workspace', async () => {
    await service.createTask({ title: 'Task 1', workspaceId: 'ws-1' });
    await service.createTask({ title: 'Task 2', workspaceId: 'ws-1' });
    await service.createTask({ title: 'Task 3', workspaceId: 'ws-2' });

    const tasks = await taskRepo.findByWorkspace('ws-1');

    expect(tasks).toHaveLength(2);
  });
});

// Illustrative API contract definition
import { z } from 'zod';

export const WorkspaceContract = {
  getWorkspace: {
    input: z.object({
      id: z.guid()
    }),
    output: z.object({
      id: z.guid(),
      name: z.string(),
      status: z.enum(['active', 'archived']),
      memberCount: z.number(),
      createdAt: z.string().datetime()
    })
  },

  createWorkspace: {
    input: z.object({
      name: z.string().min(3),
      memberLimit: z.number().optional()
    }),
    output: z.object({
      id: z.guid(),
      name: z.string(),
      status: z.literal('active'),
      memberLimit: z.number()
    })
  }
};

// Producer test - verify service honors contract
describe('WorkspaceAPI - Producer Contract', () => {
  it('getWorkspace returns valid response', async () => {
    const workspace = await createTestWorkspace();

    const response = await api.getWorkspace({ id: workspace.id });

    // Verify response matches contract
    expect(() => {
      WorkspaceContract.getWorkspace.output.parse(response);
    }).not.toThrow();
  });

  it('createWorkspace accepts valid input and returns valid output', async () => {
    const input = { name: 'Test Workspace', memberLimit: 20 };

    // Verify input is valid
    expect(() => {
      WorkspaceContract.createWorkspace.input.parse(input);
    }).not.toThrow();

    const response = await api.createWorkspace(input);

    // Verify output matches contract
    expect(() => {
      WorkspaceContract.createWorkspace.output.parse(response);
    }).not.toThrow();
  });
});

// Consumer test - verify consumer can handle producer responses
describe('WorkspaceAPI - Consumer Contract', () => {
  it('handles workspace response', () => {
    // Mock response that matches contract
    const mockResponse = {
      id: '123e4567-e89b-12d3-a456-426614174000',
      name: 'My Workspace',
      status: 'active' as const,
      memberCount: 5,
      createdAt: '2024-11-17T00:00:00Z'
    };

    // Consumer code should handle this
    expect(() => {
      const workspace = parseWorkspaceResponse(mockResponse);
      expect(workspace.name).toBe('My Workspace');
    }).not.toThrow();
  });
});

// Event schema contract
export const WorkspaceEvents = {
  'workspace.created': z.object({
    workspaceId: z.guid(),
    name: z.string(),
    ownerId: z.guid(),
    createdAt: z.string().datetime()
  }),

  'workspace.member.added': z.object({
    workspaceId: z.guid(),
    userId: z.guid(),
    role: z.enum(['owner', 'admin', 'member']),
    addedAt: z.string().datetime()
  })
};

// Producer test
it('emits valid workspace.created event', async () => {
  const event = await captureEvent('workspace.created', () => {
    return createWorkspace({ name: 'Test' });
  });

  // Verify event matches schema
  expect(() => {
    WorkspaceEvents['workspace.created'].parse(event);
  }).not.toThrow();
});

// Consumer test
it('handles workspace.created event', async () => {
  const mockEvent = {
    workspaceId: '123e4567-e89b-12d3-a456-426614174000',
    name: 'Test Workspace',
    ownerId: '234e5678-e89b-12d3-a456-426614174000',
    createdAt: '2024-11-17T00:00:00Z'
  };

  // Consumer should handle valid events
  expect(async () => {
    await handleWorkspaceCreated(mockEvent);
  }).not.toThrow();
});

// Aspirational: capture events from an event store (not present in Tuturuuu)
export async function captureEventSequence(
  workspaceId: string,
  startTime: Date,
  endTime: Date
): Promise<DomainEvent[]> {
  return await eventStore.query({
    workspaceId,
    from: startTime,
    to: endTime,
    orderBy: 'timestamp'
  });
}

// Replay events in test environment
export async function replayEvents(events: DomainEvent[]) {
  // Reset test environment
  await resetTestDatabase();

  // Replay each event in order
  for (const event of events) {
    await eventBus.publish(event);
    await waitForEventProcessing();
  }
}

// Test by replaying production scenario
describe('Bug: Workspace members not receiving invitations', () => {
  it('reproduces production bug', async () => {
    // Capture events from production incident
    const events = await captureEventSequence(
      'ws-problematic',
      new Date('2024-11-15T14:00:00Z'),
      new Date('2024-11-15T14:05:00Z')
    );

    // Replay in test environment
    await replayEvents(events);

    // Verify bug is reproduced
    const invitations = await getInvitations('ws-problematic');
    expect(invitations).toHaveLength(0); // Bug: no invitations sent
  });

  it('verifies fix resolves the issue', async () => {
    // Apply the fix (code changes)

    // Replay same event sequence
    const events = await captureEventSequence(
      'ws-problematic',
      new Date('2024-11-15T14:00:00Z'),
      new Date('2024-11-15T14:05:00Z')
    );

    await replayEvents(events);

    // Verify fix worked
    const invitations = await getInvitations('ws-problematic');
    expect(invitations).toHaveLength(3); // Fix: invitations sent correctly
  });
});

// Test edge cases by constructing event sequences
describe('Workspace state transitions', () => {
  it('handles rapid member additions and removals', async () => {
    const events = [
      createEvent('workspace.created', { id: 'ws-1' }),
      createEvent('member.added', { userId: 'user-1' }),
      createEvent('member.added', { userId: 'user-2' }),
      createEvent('member.removed', { userId: 'user-1' }),
      createEvent('member.added', { userId: 'user-3' }),
      createEvent('member.removed', { userId: 'user-2' }),
    ];

    await replayEvents(events);

    const workspace = await getWorkspace('ws-1');
    expect(workspace.members).toHaveLength(1);
    expect(workspace.members[0].userId).toBe('user-3');
  });
});

# How affected work is scoped locally and in CI
bun turbo run test --filter=@tuturuuu/web
bun turbo run build --filter=@tuturuuu/finance

// turbo.json (real key is "tasks", not "pipeline")
{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "test": {
      "cache": true
    },
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "!.next/cache/**", "dist/**"],
      "cache": true
    }
  }
}

.github/workflows/
├── vercel-preview-finance.yaml    // Finance app preview/deploy
├── vercel-preview-calendar.yaml   // Calendar app preview/deploy
├── vercel-preview-drive.yaml      // Drive app preview/deploy
├── vercel-preview-apps.yaml       // Shared preview orchestration
└── rust-backend.yml               // apps/backend (Rust) build + deploy

// Conceptual: canary deployment (Vercel handles atomic deploy + instant rollback)
// New version serves 10% of traffic initially

// vercel.json
{
  "name": "tuturuuu-finance",

  // Vercel automatically does canary deployments
  // 1. Deploy new version
  // 2. Route 10% traffic to new version
  // 3. Monitor error rates
  // 4. Gradually increase to 100% if healthy
  // 5. Automatic rollback if error rates spike
}

// Feature flags for gradual feature rollout
export async function getFinanceFeatures(workspaceId: string) {
  const flags = await featureFlags.get(workspaceId);

  return {
    advancedReports: flags.has('finance.advanced-reports'),
    aiForecasting: flags.has('finance.ai-forecasting'),
    multiCurrency: flags.has('finance.multi-currency'),
  };
}

// Enable feature for specific workspaces first
await featureFlags.enable('finance.ai-forecasting', {
  workspaces: ['ws-beta-1', 'ws-beta-2'] // Beta test
});

// Monitor performance and errors
const metrics = await monitorFeature('finance.ai-forecasting', '24h');

if (metrics.errorRate < 0.01 && metrics.userSatisfaction > 0.8) {
  // Gradually roll out to more users
  await featureFlags.enable('finance.ai-forecasting', {
    percentage: 50 // 50% of all workspaces
  });
}

// Full rollout after validation
await featureFlags.enable('finance.ai-forecasting', {
  percentage: 100 // Everyone
});

// Run migrations on "green" environment
// Switch traffic after validation

// 1. Green environment: Apply migration
await supabase.rpc('run_migration', {
  migration: '20241117_add_ai_forecasting'
});

// 2. Verify green environment health
const healthy = await verifyGreenEnvironment();

if (healthy) {
  // 3. Switch traffic from blue to green
  await switchTraffic('blue' -> 'green');

  // 4. Monitor for issues
  setTimeout(() => {
    if (metricsLookGood()) {
      // 5. Destroy blue environment
      destroyBlueEnvironment();
    } else {
      // Rollback: Switch back to blue
      switchTraffic('green' -> 'blue');
    }
  }, 3600000); // Monitor for 1 hour
}

// .env.example - template for all environments
// Developers, staging, and production use same variables

NEXT_PUBLIC_SUPABASE_URL=
SUPABASE_SECRET_KEY=
TRIGGER_API_KEY=
DATABASE_URL=

// Environment-specific .env files
// .env.local (development)
// .env.staging (staging)
// .env.production (production)

// All have same structure, different values

// vercel.json ensures consistency
{
  "env": {
    // Required in all environments
    "NEXT_PUBLIC_SUPABASE_URL": "@supabase-url",
    "SUPABASE_SECRET_KEY": "@supabase-service-key"
  },

  "build": {
    "env": {
      // Build-time variables. The platform version is owned by Release Please
      // and read from TUTURUUU_PLATFORM_VERSION in
      // packages/utils/src/platform-release.ts — do not hard-code a literal here.
      "NEXT_PUBLIC_APP_VERSION": "$TUTURUUU_PLATFORM_VERSION"
    }
  }
}

# Illustrative Dockerfile — keep versions aligned with package.json pins
FROM oven/bun:1.3.14 as base

WORKDIR /app

# Install dependencies (frozen lockfile => same versions everywhere)
COPY package.json bun.lock ./
RUN bun install --frozen-lockfile

COPY . .
RUN bun run build

# Production image (identical across environments)
FROM oven/bun:1.3.14-slim
WORKDIR /app
COPY --from=base /app/.next ./.next
COPY --from=base /app/node_modules ./node_modules
COPY --from=base /app/package.json ./

CMD ["bun", "run", "start"]

# Start local Supabase (mirrors the production schema)
bun sb:start

# Author and apply migrations locally
bun sb:new      # scaffold a new migration
bun sb:up       # apply migrations to the local database

# Regenerate DB types after schema changes
bun sb:typegen