Workspace Management
Relevant source files
The following files were used as context for generating this wiki page:
- apps/web/src/app/[locale]/(dashboard)/[wsId]/(workspace-settings)/infrastructure/workspaces/page.tsx
- packages/ui/src/lib/workspace-actions.ts
- apps/web/src/app/[locale]/(dashboard)/[wsId]/navigation.tsx
- conductor/tracks/workforce_20251225/spec.md
- apps/web/src/app/[locale]/(dashboard)/[wsId]/(workspace-settings)/usage/_components/stats.tsx
- apps/nova/messages/en.json
- apps/meet/messages/en.json
Workspace Management is the core organizational system of the Tuturuuu platform, serving as an intelligent operating system for work and life. It provides a multi-tenant environment where users can create, join, and manage distinct workspaces for different projects, organizations, or personal use. This system unifies various modules—including finance, tasks, AI resources, and inventory—under a centralized governance model that handles security, permissions, and resource allocation.
The architecture separates administrative platform-wide infrastructure from individual workspace settings. It supports a dual-layer identity model that distinguishes between active "Workspace Members" (platform authentication accounts) and "Workspace Users" (HR/virtual records for historical and financial tracking).
Workspace Hierarchy and Types
The platform distinguishes between several types of workspaces to cater to different use cases. Personal workspaces are automatically matched to a user's account display name or email, while organizational workspaces allow for team-based collaboration and infrastructure-level management.
Workspace Categories
- Personal Workspace: Automatically created for eligible internal accounts; naming follows account display names or emails.
- Organizational Workspace: Created for team collaboration with shared resources and roles.
- Root Workspace: A special administrative workspace (
ROOT_WORKSPACE_ID) that holds platform-level permissions and infrastructure access.
Sources: apps/web/src/app/[locale]/(dashboard)/[wsId]/navigation.tsx, apps/meet/messages/en.json, packages/ui/src/lib/workspace-actions.ts
Visualizing Workspace Discovery
The following diagram illustrates how the system resolves and fetches workspaces for a user, including the resolution of personal workspace data.
This flow ensures that personal workspaces always reflect the user's current identity regardless of the stored workspace name.
Sources: packages/ui/src/lib/workspace-actions.ts:7-60
Identity and Access Management
Access control is governed by a robust permissions and role system. This system manages both platform-level roles and workspace-specific roles, ensuring that users have appropriate access to sensitive features like finance, AI execution, and infrastructure settings.
Permissions and Security
The system uses granular permissions to gate access to specific modules. Key permissions include:
manage_workspace_members: For inviting and removing users.manage_workspace_roles: For configuring permission sets.manage_workspace_secrets: For platform-level configuration values.view_infrastructure: For accessing platform-wide analytics and workspace oversight.
Sources: apps/web/src/app/[locale]/(dashboard)/[wsId]/(workspace-settings)/usage/_components/stats.tsx, apps/meet/messages/en.json
Workforce Identity Layers
A significant architectural feature is the "Dual-Layer Identity," which bridges active platform participation with HR-focused record-keeping.
| Layer | Description | Purpose |
|---|---|---|
| Workspace Member | Active authentication account linked to a platform user ID. | Used for platform interaction, task assignment, and real-time collaboration. |
| Workspace User (Virtual) | HR record containing sensitive data (TIN, Bank info, etc.). | Used for historical records, external contractors, and payroll processing. |
Sources: conductor/tracks/workforce_20251225/spec.md:9-25
Infrastructure Oversight
Platform administrators use the Infrastructure area to monitor the health and usage of all workspaces globally. This includes tracking total counts, tiers, and status distributions across the entire ecosystem.
Monitoring Metrics
The infrastructure dashboard aggregates critical data to ensure platform stability:
- Workspace Overview: Total workspace counts, status tracking (active/deleted), and tier distribution.
- Usage Stats: Monitoring storage (Drive), AI executions, and transaction counts across workspaces.
- Security Logs: Tracking API key usage and audit logs.
Sources: apps/web/src/app/[locale]/(dashboard)/[wsId]/(workspace-settings)/infrastructure/workspaces/page.tsx:40-65, apps/web/src/app/[locale]/(dashboard)/[wsId]/(workspace-settings)/usage/_components/stats.tsx:10-150
Configuration and Secrets
Workspaces are highly configurable through a system of "Workspace Configs" and "Secrets." These allow for customization of default routes, feature visibility (e.g., invoice visibility), and external integration keys.
Key Configuration Elements
- Default Routes: Priorities are set as
User Preference > Workspace Setting > Default. - Secrets Management: Secured keys for external API access (e.g.,
GOOGLE_GENERATIVE_AI_API_KEY). - Feature Flags: Controlling access to experimental features like
ENABLE_AI_ONLYorENABLE_DOCS.
Sources: apps/web/src/app/[locale]/(dashboard)/[wsId]/navigation.tsx:100-150, apps/meet/messages/en.json
API and SDK Integration
Workspaces provide dedicated API keys for external access. The official SDK facilitates secure interactions with workspace storage and documents.
// Initializing SDK within a workspace context
import { TuturuuuClient } from 'tuturuuu';
const client = new TuturuuuClient(process.env.TUTURUUU_API_KEY);
// Permissions required: manage_drive
const files = await client.storage.list({ path: 'documents' });
Sources: apps/web/src/app/[locale]/(dashboard)/[wsId]/(workspace-settings)/api-keys/sdk-guide.tsx:10-150
Conclusion
Workspace Management in Tuturuuu is a sophisticated multi-layered system that balances user-friendly personal environments with powerful enterprise-grade administrative controls. By separating the active membership from virtual HR identities and providing deep infrastructure oversight, the platform enables scalable organizational growth while maintaining strict security and resource management standards.