Organization Setup Implementation Guide

Created: 2025-08-08
Status: Implementation Plan
Purpose: Comprehensive guide for implementing Organization Setup with document conversion and Claude research integration

Overview

Organization Setup is a critical onboarding feature that helps Sasha understand a user's organization through document upload and automated research. This guide documents the complete implementation plan for this feature.

Key Features

• Document-first approach: Users upload business documents (PDFs, Word, Excel, PowerPoints)
• Automatic conversion: Documents converted to Markdown using @knowcode/convert-to-markdown
• Skip functionality: Users can skip and access later from Settings
• Visible research: Claude performs research in a visible session, educating users
• Privacy-focused: Strong messaging about private instance and data security

Architecture

Document Processing Pipeline

User Uploads → Convert to MD → Save to docs/local/ → Index → Claude Research → docs/organization/

Directory Structure

~/.claude/projects/default-workspace/
├── CLAUDE.md                           # Organization context
├── docs/
│   ├── local/                         # Converted user documents
│   │   ├── contracts/
│   │   │   └── service-agreement.md
│   │   ├── presentations/
│   │   │   └── company-overview.md
│   │   ├── handbooks/
│   │   │   └── employee-manual.md
│   │   └── index.md                   # Auto-generated document index
│   ├── guides/
│   │   └── organization-research-guide.md
│   └── organization/                  # Claude's research output
│       ├── company-overview.md
│       ├── team-structure.md
│       ├── products-services.md
│       └── market-analysis.md

User Experience Flows

First-Time User Flow

1. Login → Organization Setup screen appears
2. Option to Skip (top right, subtle but findable)
3. Upload Documents → Drag & drop business documents
4. Conversion → Documents converted to MD, shown in progress
5. Review → Confirm company details
6. Complete → Navigate to default-workspace
7. Auto-Launch → Claude starts research session automatically

Skip Flow

1. User clicks "Skip for now →"
2. System creates empty default-workspace
3. User lands in empty workspace
4. Can access Organization Setup later from Settings

Re-Access Flow

1. From Settings Menu: Click "Organization Setup"
2. From Empty Workspace: Click setup card
3. Complete Setup: Same flow as first-time
4. Research Launches: Claude performs visible research

Technical Implementation

1. Files to Modify

A. Rename and Update Component

• From: src/components/GettingStartedScreen.jsx
• To: src/components/OrganizationSetupScreen.jsx
• Add skip button functionality
• Update title to "Organization Setup"
• Show document conversion progress

B. Update Routes

• File: server/routes/profile.js
• Add /organization/skip endpoint
• Update /organization/complete endpoint
• Add document processing logic

C. Update Sidebar

• File: src/components/Sidebar.jsx
• Add "Organization Setup" menu item in Settings
• Show completion status badge
• Handle navigation to setup screen

D. Update Auth Context

• File: src/contexts/AuthContext.jsx
• Add organizationSetupCompleted state
• Add skip and complete functions
• Handle navigation after completion

E. Update Protected Route

• File: src/components/ProtectedRoute.jsx
• Check organization setup status
• Show OrganizationSetupScreen when needed

2. Files to Create

A. Workspace Manager

File: server/services/workspace-manager.js

export async function setupOrganizationWorkspace(userId, organizationData) {
  // Create default-workspace directory
  // Set up docs/ structure
  // Copy research guide
  // Create initial CLAUDE.md
}

export async function createDocumentIndex(documents, workspacePath) {
  // Generate index.md with document listing
  // Include metadata and structure
}

B. Enhanced Document Processor

File: Update server/services/document-processor.js

import { convertToMarkdown } from '@knowcode/convert-to-markdown';

export async function processOrganizationDocuments(files, workspacePath) {
  // Convert each file to markdown
  // Preserve directory structure
  // Save to docs/local/
  // Return processed document list
}

C. Research Guide

File: docs/guides/organization-research-guide.md

# Organization Research Guide

## Phase 1: Document Analysis
- Review all documents in docs/local/
- Extract key information
- Identify stakeholders and structure

## Phase 2: Web Research
- Research company website
- Find recent news and updates
- Analyze industry and competitors

## Phase 3: Knowledge Base Creation
- Create structured documents in docs/organization/
- Synthesize findings
- Build comprehensive knowledge base

3. Database Schema Updates

File: server/database/init.sql

ALTER TABLE company_profiles ADD COLUMN organization_setup_completed BOOLEAN DEFAULT 0;
ALTER TABLE company_profiles ADD COLUMN setup_method VARCHAR(20) DEFAULT 'pending';
-- Values: 'documents', 'manual', 'skipped', 'pending'

4. API Endpoints

Skip Organization Setup

POST /api/profile/organization/skip
Authorization: Bearer {token}

Response:
{
  "success": true,
  "workspacePath": "/path/to/default-workspace",
  "skipped": true
}

Complete Organization Setup

POST /api/profile/organization/complete
Authorization: Bearer {token}
Content-Type: multipart/form-data

Body:
- documents[] (files)
- companyName
- website
- industry

Response:
{
  "success": true,
  "workspacePath": "/path/to/default-workspace",
  "documentsProcessed": 5,
  "researchPrompt": "..."
}

Document Conversion Details

Using @knowcode/convert-to-markdown

Following the existing guide at docs/private/guides/knowledge-management/excel-to-markdown-conversion-technique.md:

const { convertToMarkdown } = require('@knowcode/convert-to-markdown');

async function convertDocument(file) {
  const fileBuffer = await fs.readFile(file.path);
  
  const markdown = await convertToMarkdown(fileBuffer, {
    fileType: file.mimetype,
    fileName: file.originalname
  });
  
  return markdown;
}

Supported File Types

• PDF (.pdf)
• Word (.doc, .docx)
• Excel (.xls, .xlsx)
• PowerPoint (.ppt, .pptx)
• Text (.txt, .md)
• Images (.png, .jpg, .jpeg)

File Naming Convention

• Original: Company-Presentation-2025.pptx
• Converted: company-presentation-2025.md
• Location: docs/local/presentations/company-presentation-2025.md

Claude Research Session

Auto-Launch Implementation

In MainContent.jsx:

useEffect(() => {
  if (navigationState?.fromOrganizationSetup) {
    const researchPrompt = `
      I'll now help you build a comprehensive knowledge base for ${organizationName}.
      
      I can see you've uploaded ${documentCount} documents to docs/local/.
      Following the organization research guide, I'll:
      
      1. Analyze your uploaded documents
      2. Research additional information online
      3. Create structured knowledge documents
      
      Let me start by reviewing your documents...
      [Reading docs/local/...]
    `;
    
    sendMessage(researchPrompt);
  }
}, [navigationState]);

Research Output Structure

Claude will create documents in docs/organization/:

• company-overview.md - Mission, values, history
• team-structure.md - Key people and roles
• products-services.md - Offerings and capabilities
• market-analysis.md - Industry position and competitors
• extracted-insights.md - Key findings from uploaded documents

Testing Plan

Test Scenarios

1. First-Time User

   • Organization Setup appears after login
   • Can upload documents successfully
   • Documents convert to markdown
   • Claude session launches automatically

2. Skip Functionality

   • Skip button is visible but not prominent
   • Clicking skip creates default-workspace
   • User lands in empty workspace
   • Can access setup from Settings

3. Re-Access

   • Settings menu shows Organization Setup
   • Badge shows "Not completed" if skipped
   • Can complete setup later
   • Research launches after completion

4. Document Conversion

   • PDFs convert successfully
   • Excel files preserve structure
   • PowerPoints maintain content
   • Directory structure preserved

5. Research Session

   • Claude reads research guide
   • Analyzes docs/local/ content
   • Performs web research
   • Creates organization documents

Validation Checklist

• All file types convert properly
• Skip flow works correctly
• Re-access from Settings works
• Claude session auto-launches
• Documents saved to correct locations
• Privacy messaging displays
• Phosphor icons display correctly
• Mobile responsive design works

Security Considerations

Privacy Assurances

• Strong messaging about private instance
• Documents stored locally only
• No external sharing
• Encrypted storage references

File Handling

• Maximum file size: 50MB per file
• Maximum total upload: 500MB
• Virus scanning (if implemented)
• Secure file paths (no directory traversal)

Implementation Priority

1. Phase 1: Core Functionality

   • Create workspace manager
   • Update document processor
   • Implement skip functionality
   • Rename to OrganizationSetupScreen

2. Phase 2: Integration

   • Add to Settings menu
   • Update database schema
   • Create API endpoints
   • Handle navigation flows

3. Phase 3: Research Integration

   • Create research guide
   • Implement auto-launch
   • Test Claude session
   • Validate output

Success Metrics

• Users can skip setup and start immediately
• 80% of users who start setup complete it
• Documents convert successfully 95% of time
• Claude research provides valuable insights
• Users understand system capabilities through visible research

Future Enhancements

• Industry-specific research guides
• Bulk document upload from cloud storage
• OCR for scanned documents
• Multi-language support
• Custom research parameters
• Scheduled research updates

References

• Excel to Markdown Guide: docs/private/guides/knowledge-management/excel-to-markdown-conversion-technique.md
• @knowcode/convert-to-markdown: npm package
• Original Getting Started Screen: src/components/GettingStartedScreen.jsx
• Document Processor: server/services/document-processor.js