Getting Started with Org App

This guide will help you set up the Org App and configure your organization, workspaces, and attributes.

Prerequisites

Before using the Org App, ensure you have:

• Access to the FlowState platform
• Administrative permissions for organization management
• (Optional) GitHub or external API credentials for sync configuration

Accessing the App

1. Navigate to the FlowState app launcher
2. Click on Organizations (blue building icon)
3. The app opens at /apps/org/orgs

Initial Setup

The Org App is the foundation of FlowState's multi-tenant architecture. Follow these steps to set up your organization hierarchy.

Step 1: Create Your Organization

An organization is the top-level container for all your FlowState data.

1. Navigate to the Orgs page (/apps/org/orgs)
2. Click the Create Organization button
3. Enter organization details:
   • Name: Your organization name (e.g., "Acme Corp")
   • Description: Optional description of the organization
4. Click Save to create the organization
5. The organization is automatically selected if no organization was previously selected

Step 2: Create Your First Workspace

Workspaces organize work within an organization. You might have workspaces for different teams, projects, or departments.

1. Navigate to the Workspaces page (/apps/org/workspaces)
2. Click the Create Workspace button
3. Enter workspace details:
   • Name: Workspace name (e.g., "Engineering", "Marketing")
   • Organization: Select the parent organization
   • Description: Optional workspace description
4. Click Save to create the workspace
5. The workspace is automatically selected if no workspace was previously selected

Step 3: Configure Attributes

Attributes (categories and tags) help classify and organize entities across FlowState. You can seed default attributes or create custom ones.

Option A: Seed Default Attributes

The fastest way to get started:

1. Navigate to the Attributes page (/apps/org/attributes)
2. Click Seed Defaults (shown when no attributes exist)
3. Select one or more preset types:
   • Project Categories: Development, Design, Marketing, etc.
   • Task Tags: Priority levels, status indicators, etc.
   • General: Common organizational attributes
4. Click Seed to create the attributes
5. Review the seeding results

Option B: Create Custom Attributes

For custom organizational needs:

1. Navigate to the Attributes page
2. Click the Create Attribute button
3. Select attribute type:
   • Category: For grouping entities (e.g., "Department", "Project Type")
   • Tag: For labeling entities (e.g., "Urgent", "Needs Review")
4. Enter attribute details:
   • Title: Display name
   • Name: System identifier (auto-generated from title)
   • Description: Optional description
   • Color: Select from the color palette
5. Click Save to create the attribute

Step 4: Add Users (Optional)

Review and manage users within your organization:

1. Navigate to the Users page (/apps/org/users)
2. View the user directory for your organization
3. Search and filter users as needed
4. User invitations and role management may be handled through platform settings

Step 5: Configure External Sync (Optional)

Connect external data sources like GitHub:

1. Navigate to the Sync page (/apps/org/sync)
2. Select a sync provider:
   • GitHub: Sync repositories, issues, and pull requests
   • Custom API: Connect custom data endpoints
3. Click Connect to initiate the OAuth flow (if required)
4. Complete authentication in the popup window
5. Configure sync settings (repositories, polling interval, etc.)
6. Enable the sync connection

Navigation Overview

Once setup is complete, use the sidebar to navigate:

Understanding the Hierarchy

The Org App establishes this data hierarchy for FlowState:

Organization (top-level tenant)
├── Workspaces (logical groupings)
│   ├── Projects (via Projects App)
│   ├── Tasks (via Todo App)
│   └── Other entities...
├── Users (organization members)
└── Attributes (shared categories/tags)

• Organization isolation: Data is isolated between organizations
• Workspace scoping: Most entities belong to a specific workspace
• Attribute inheritance: Attributes can be org-wide or workspace-specific

Selection Persistence

Your organization and workspace selections are persisted to local storage:

• Selections are remembered across browser sessions
• New organizations/workspaces are auto-selected when created (if none selected)
• The current selection affects which data is shown in other FlowState apps

Next Steps

Once you've completed the initial setup:

• Explore Features to learn about all capabilities
• Check out Creating a Workspace for detailed workflow guidance
• Review FAQ for answers to common questions
• See Troubleshooting if you encounter issues