Org App - Features & Capabilities Report

Template Version: 1.0.0 Generated: 2026-01-22 Package: @epicdm/flowstate-app-org App ID: org

Table of Contents

1. Overview
2. App Identity
3. Feature Categories
4. Capabilities
5. Data Models
6. User Workflows
7. Integration Points
8. Architecture Summary
9. Quality & Compliance

Overview

Purpose

The Org App is the central administration application for FlowState. It provides comprehensive management of organizations, workspaces, users, and attributes (categories and tags). It also handles external sync configuration for integrating with third-party services like GitHub. This app establishes the foundational multi-tenant structure that all other FlowState applications depend on.

Target Users

Value Proposition

• Multi-Tenant Foundation: Organizations > Workspaces hierarchy
• Attribute System: Flexible categories and tags for entity classification
• External Sync: Connect to GitHub and custom APIs
• OAuth Integration: Secure third-party authentication
• Preset Seeding: Quick setup with predefined attribute sets

App Identity

Entry Points

Feature Categories

Category 1: Organization Management

Manage multi-tenant organizations

Feature: Organization CRUD Operations

Description: Create, view, edit, and manage organizations. Organizations serve as the top-level tenant container for all FlowState data.

User Story: As a system administrator, I want to manage organizations so that I can support multiple tenants with data isolation.

Acceptance Criteria:

• [x] Create organizations with name and metadata
• [x] View organizations in list view
• [x] Edit organization details
• [x] Auto-select newly created org if none selected
• [x] Persist selection to localStorage

Implementation:

Routes:

• /orgs - Organization list and management

Category 2: Workspace Management

Organize work into logical workspaces

Feature: Workspace CRUD Operations

Description: Create and manage workspaces within organizations. Workspaces provide logical groupings of projects, tasks, and other entities.

User Story: As an organization owner, I want to create workspaces so that I can organize work into logical groupings.

Acceptance Criteria:

• [x] Create workspaces within organizations
• [x] View workspaces in list view
• [x] Edit workspace details
• [x] Auto-select newly created workspace if none selected
• [x] Persist selection to localStorage

Implementation:

Routes:

• /workspaces - Workspace list and management

Category 3: User Management

View and manage organization users

Feature: User Directory

Description: View and manage users within the organization. Provides a directory of all organization members.

User Story: As an organization owner, I want to view users so that I can manage organization membership.

Acceptance Criteria:

• [x] View users in list view
• [x] Display user details and roles
• [x] Filter and search users

Implementation:

Routes:

• /users - User directory

Category 4: Attribute Management

Define categories and tags for entity classification

Feature: Attribute CRUD Operations

Description: Create, edit, and delete attributes (categories and tags) that apply across the organization. Attributes can be seeded from presets or created manually.

User Story: As an organization owner, I want to define attributes so that I can classify and organize entities consistently.

Acceptance Criteria:

• [x] Create categories with title, name, description, color
• [x] Create tags with title, name, description, color
• [x] Edit existing attributes
• [x] Delete attributes
• [x] Archive attributes
• [x] Color picker with default palette

Implementation:

Routes:

• /attributes - Attribute management

Feature: Attribute Seeding

Description: Seed attributes from predefined presets for quick setup. Multiple preset types are available for different use cases.

User Story: As an organization owner, I want to seed default attributes so that I can quickly set up standard categories and tags.

Acceptance Criteria:

• [x] Seed from single preset
• [x] Seed from multiple presets
• [x] Skip existing attributes to prevent duplicates
• [x] Show seed button when no attributes exist
• [x] Report seeding results

Implementation:

Category 5: Sync Configuration

Configure external data source synchronization

Feature: Sync Settings

Description: Configure synchronization with external data sources including GitHub and custom APIs. Supports OAuth authentication for secure connections.

User Story: As a workspace administrator, I want to configure sync providers so that I can integrate external data into FlowState.

Acceptance Criteria:

• [x] View available sync providers
• [x] Configure provider settings
• [x] Register built-in providers (GitHub, Custom API)
• [x] Handle OAuth authentication flows

Implementation:

Routes:

• /sync - Sync configuration

Feature: OAuth Callback Handling

Description: Handle OAuth callbacks from external sync providers, completing the authentication flow.

User Story: As a user, I want OAuth callbacks handled automatically so that my authentication completes seamlessly.

Acceptance Criteria:

• [x] Handle provider-specific callbacks
• [x] Redirect to sync page on success
• [x] Redirect to sync page with error on failure
• [x] Support multiple providers

Implementation:

Routes:

• /sync/callback/:providerId - OAuth callback endpoint

Capabilities

Core Capabilities

Technical Capabilities

Integration Capabilities

Data Models

Collections Used

Entity Relationships

Organization
    |
    +-- Workspaces (hasMany)
    |       |
    |       +-- Projects (hasMany)
    |       |
    |       +-- Tasks (hasMany)
    |       |
    |       +-- Attributes (hasMany, scoped)
    |
    +-- Users (hasMany, via membership)
    |
    +-- Attributes (hasMany, org-level)

Key Data Flows

User Action --> Component --> Framework Component --> RxDB Collection --> UI Update
                                     |
                                     +--> Service (AttributeSeedService)
                                     |
                                     +--> Replication --> Server

User Workflows

Workflow 1: Organization Setup

Initial organization creation and configuration

Trigger: New user or system administrator

Steps:

Success Outcome: Organization fully configured with workspace and attributes Failure Handling: Validation errors shown, state preserved

Workflow 2: Attribute Management

Create custom attributes for entity classification

Trigger: Need to categorize or tag entities

Steps:

Success Outcome: New attribute available for entity classification Failure Handling: Validation errors shown in modal

Workflow 3: Sync Configuration

Connect external data source

Trigger: Need to import data from GitHub or API

Steps:

Success Outcome: External data source connected Failure Handling: Error redirect with message

Integration Points

Internal Integrations

External Integrations

MCP Integration

Architecture Summary

Directory Structure

src/
├── components/          # UI components
│   ├── Header.tsx      # App header
│   └── Sidebar.tsx     # Navigation sidebar
├── db/                 # Database configuration
│   ├── collections.ts  # Collection exports
│   ├── schema.ts       # Schema exports
│   └── types.ts        # Type exports
├── pages/              # Page components
│   ├── AttributesPage.tsx        # Attribute management
│   ├── OrganizationsPage.tsx     # Org management
│   ├── SyncOAuthCallbackPage.tsx # OAuth callback
│   ├── SyncPage.tsx              # Sync settings
│   ├── UsersPage.tsx             # User directory
│   └── WorkspacesPage.tsx        # Workspace management
├── App.tsx             # Main app with routing
├── index.ts            # Package exports
├── plugin.ts           # FlowState plugin config
├── standalone.tsx      # Standalone entry
└── styles.css          # App styles

Key Architectural Patterns

Framework Delegation

The Org App delegates most functionality to the FlowState App Framework:

Quality & Compliance

Test Coverage

Accessibility

Security Considerations

FlowState Alignment

Spec-Driven Development

This app follows the FlowState Standard for spec-driven development:

• Requirements: .flowstate/specs/{{feature-name}}/requirements.md
• Design: .flowstate/specs/{{feature-name}}/design.md
• Wireframes: .flowstate/specs/{{feature-name}}/wireframes.html
• Tasks: .flowstate/specs/{{feature-name}}/tasks.md

Quality Gates

Appendix

Related Documentation

Version History