Getting Started & Configuration

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• GEMINI.md
• conductor/workflow.md
• apps/backend/README.md
• apps/web/src/app/[locale]/(dashboard)/[wsId]/(workspace-settings)/api-keys/sdk-guide.tsx
• packages/supabase/QUICKSTART.md

The Tuturuuu platform is a complex monorepo ecosystem managed with Turborepo and bun. It integrates a wide array of services including workspace management, AI chatbots, financial tracking, and task management. This guide outlines the essential steps for environment setup, local development, and the configuration patterns used across the repository.

The architecture relies on a shared package system where core logic, UI components, and database clients are centralized to serve multiple frontend applications (like web, tasks, and rewise) and backend services.

Sources: README.md:1-20, GEMINI.md:5-15

Environment Setup & Prerequisites

Before starting development, the local machine must be equipped with specific runtimes and tools to handle the monorepo structure and local database environment.

System Requirements

• Runtime: Node.js v22+ and Bun v1.3+ are mandatory for package management and script execution.
• Database: Docker is required to run the local Supabase instance.
• Package Manager: The project exclusively uses bun workspaces.

Sources: README.md:183-190, GEMINI.md:31-35

Initializing the Repository

The setup process involves cloning the repository, installing dependencies via bun, and initializing the local Supabase environment.

# Install dependencies
bun i

# Start Supabase (requires Docker)
bun sb:start

# Build shared packages (Required for first-time setup)
bun run build

Sources: README.md:195-207, packages/supabase/QUICKSTART.md:5-10

The following diagram illustrates the initial setup flow for a new developer:

The flow ensures that shared packages are compiled before the applications that depend on them are launched.

Sources: README.md:195-212, packages/supabase/QUICKSTART.md:20-25

Development Workflow

The project follows a strict workflow managed by an automated "Conductor" and standardized commands.

Key Development Commands

Command	Purpose
bun dev	Starts all applications in development mode using Turborepo.
bun type-check	Runs TypeScript compiler checks across the entire monorepo.
bun test	Executes the Vitest suite for all packages and apps.
bun check	Unified verification command running linting, tests, and type-checks.
bun sb:typegen	Generates TypeScript types directly from the Supabase schema.

Sources: README.md:215-245, GEMINI.md:45-55

Task Lifecycle

Development tasks follow a Test-Driven Development (TDD) cycle. Developers must track progress in a plan.md file and verify code coverage.

Configuration Management

The platform uses a layered configuration approach involving environment variables, package-level configurations, and workspace settings.

Environment Variables

Each application contains a .env.example template. Developers must create a .env.local in each apps/* directory.

• Global Variables: Defined in turbo.json.
• Workspace Limits: Configurable via STORAGE_LIMIT_BYTES in workspace secrets (defaulting to 100MB).

Sources: GEMINI.md:75-80, apps/web/src/app/[locale]/(dashboard)/[wsId]/(workspace-settings)/api-keys/sdk-guide.tsx:342-355

Shared Package Configuration

Packages like @tuturuuu/supabase require a build step to generate distribution files in dist/. In the monorepo, these packages point to the compiled output rather than source files to ensure consistency between development and production environments.

Sources: packages/supabase/QUICKSTART.md:12-20, packages/supabase/CHANGELOG.md:30-40

SDK Integration & API Access

For external or internal service integration, the platform provides an official TypeScript SDK.

SDK Initialization

The SDK provides a type-safe interface for storage and document operations. It is recommended to initialize the client using environment variables for security.

import { TuturuuuClient } from 'tuturuuu';

// Security Best Practice: Use environment variables
const client = new TuturuuuClient(process.env.TUTURUUU_API_KEY);

Sources: apps/web/src/app/[locale]/(dashboard)/[wsId]/(workspace-settings)/api-keys/sdk-guide.tsx:25-30, apps/web/src/app/[locale]/(dashboard)/[wsId]/(workspace-settings)/api-keys/sdk-guide.tsx:180-195

Permission Scopes

API keys and SDK operations are restricted by granular permissions:

• Storage: Requires manage_drive permission.
• Documents: Requires manage_documents permission.

Sources: apps/web/src/app/[locale]/(dashboard)/[wsId]/(workspace-settings)/api-keys/sdk-guide.tsx:325-338

Backend Configuration (Rust)

The project includes an educational Rust/Axum backend in apps/backend which follows its own configuration patterns.

Backend Setup

The Rust backend requires a PostgreSQL connection string and JWT secrets.

Variable	Description	Default
DATABASE_URL	PostgreSQL connection string	postgresql://...
JWT_SECRET	Secret key for token signing	(Must be 32+ chars)
PORT	Listening port for the Axum server	3001

Sources: apps/backend/README.md:180-205

Database Migrations

Migrations for the Rust backend are handled via SQL files located in migrations/. These can be applied automatically on server start or via the sqlx-cli.
Sources: apps/backend/README.md:210-225

Conclusion

Getting started with the Tuturuuu platform requires strict adherence to the bun ecosystem and the local Supabase environment. By utilizing the unified bun check command and following the TDD workflow outlined in the conductor guidelines, developers can maintain the high code quality and type safety standards expected within the monorepo. Proper configuration of environment variables and shared package builds is critical to ensuring a functional development environment.