Design workspace_providers table schema for LLM keys, Tenderly, RPC endpoints (encrypted, tenant-scoped)

[Hyperkit-dev]

🎯 Layer 1: Intent Parsing

What needs to be done?

Task Title:

Design workspace_providers table schema for LLM keys, Tenderly, RPC endpoints (encrypted, tenant-scoped)

Area: orchestration | Repos: services/ (Shannon-like)

Primary Goal:

Design and document workspace_providers table schema for LLM keys, Tenderly, RPC endpoints (encrypted, tenant-scoped) following best practices

User Story / Context:

As a platform architect, I want to design a secure, scalable workspace_providers table schema that supports multi-tenant provider configurations (LLM keys, Tenderly, RPC endpoints) so that each workspace can manage its own provider credentials securely

Business Impact:

Enables core platform functionality and multi-tenant workspace isolation. Supports the multi-tenant workspace model described in the Business Model

Task Metadata:

• Sprint: Sprint 1
• Related Epic/Project: GitHub Project 9 - Phase 1 Foundation
• Issue Type: Feature
• Area: Orchestration
• Related Documentation:
  • Platform Blueprint - Section 1: System overview (Core Services)
  • Scope Definition - MVP Scope: Sprint 1-2
  • Execution Strategy - Section 2: Architecture Document
  • Business Model - Pillar 1: HyperAgent Cloud (SaaS)
  • Database Schema Design - Schema patterns

---

📚 Layer 2: Knowledge Retrieval

What information do I need?

Required Skills / Knowledge:

• Backend/API (FastAPI, Python)
• DevOps/Infra (CI/CD, Docker)
• Database Design (PostgreSQL, Supabase)

Estimated Effort:

M (Medium - 3-5 days)

Knowledge Resources:

• Review .cursor/skills/ for relevant patterns
• Check .cursor/llm/ for implementation examples
• Read Platform Blueprint: docs/draft.md
• Read Scope Definition: docs/planning/3-Scope-Definition.md
• Read Execution Strategy: docs/reference/spec/execute.md
• Read Database Schema Design: docs/planning/5-Database-Schema-Design.md
• Study tech docs / ADRs in docs/adrs/ directory
• Review API / schema references for relevant services
• Review Supabase best practices for encryption and RLS

Architecture Context:

According to the Platform Blueprint, HyperAgent uses Supabase (PostgreSQL) for relational data. The workspace_providers table is part of the multi-tenant workspace model that enables each workspace to configure its own provider credentials.

System Architecture Diagram:

graph TB
    subgraph "Orchestration Service"
        API[FastAPI Gateway]
        Router[Agent Router]
        State[State Manager]
        Queue[Task Queue]
        ProviderResolver[Provider Resolver]
    end
    
    subgraph "External Services"
        DB[(Supabase<br/>workspace_providers)]
        Cache[(Redis)]
        VectorDB[(Pinecone)]
    end
    
    API --> Router
    Router --> State
    Router --> Queue
    Router --> ProviderResolver
    ProviderResolver --> DB
    State --> DB
    Queue --> Cache
    Router --> VectorDB

Loading

Code Examples & Patterns:
Supabase Schema Example:

-- Workspace providers table
CREATE TABLE workspace_providers (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    workspace_id UUID NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
    provider_type VARCHAR(50) NOT NULL, -- 'llm', 'tenderly', 'rpc'
    provider_name VARCHAR(100) NOT NULL, -- 'anthropic', 'openai', 'tenderly', 'alchemy', etc.
    encrypted_config JSONB NOT NULL, -- Encrypted provider configuration
    config_metadata JSONB, -- Non-sensitive metadata (e.g., region, version)
    is_active BOOLEAN DEFAULT true,
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW(),
    created_by UUID REFERENCES users(id),
    
    -- Unique constraint: one active provider per type/name per workspace
    CONSTRAINT unique_active_provider UNIQUE (workspace_id, provider_type, provider_name, is_active)
);

-- Indexes for performance
CREATE INDEX idx_workspace_providers_workspace_id ON workspace_providers(workspace_id);
CREATE INDEX idx_workspace_providers_type ON workspace_providers(provider_type);
CREATE INDEX idx_workspace_providers_active ON workspace_providers(workspace_id, is_active) WHERE is_active = true;

-- RLS Policy: Users can only access providers for their workspace
CREATE POLICY "Users can only see their workspace providers"
ON workspace_providers FOR SELECT
USING (
    workspace_id IN (
        SELECT workspace_id FROM workspace_members 
        WHERE user_id = auth.uid()
    )
);

CREATE POLICY "Users can only insert providers for their workspace"
ON workspace_providers FOR INSERT
WITH CHECK (
    workspace_id IN (
        SELECT workspace_id FROM workspace_members 
        WHERE user_id = auth.uid()
    )
);

-- Encryption function (using pgcrypto)
CREATE OR REPLACE FUNCTION encrypt_provider_config(
    plain_config JSONB,
    encryption_key TEXT
) RETURNS JSONB AS $$
BEGIN
    -- Implementation depends on encryption strategy
    -- Could use pgcrypto or application-level encryption
    RETURN plain_config; -- Placeholder
END;
$$ LANGUAGE plpgsql;

Example Provider Configurations:

// LLM Provider (Anthropic)
{
  "api_key": "encrypted_value",
  "model": "claude-3-5-sonnet-20241022",
  "max_tokens": 4096,
  "temperature": 0.7
}

// Tenderly Provider
{
  "api_key": "encrypted_value",
  "user_name": "hyperkit",
  "project_slug": "hyperagent",
  "network_id": "1"
}

// RPC Provider (Alchemy)
{
  "api_key": "encrypted_value",
  "network": "ethereum-mainnet",
  "url": "https://eth-mainnet.g.alchemy.com/v2/{api_key}"
}

---

⚠️ Layer 3: Constraint Analysis

What constraints and dependencies exist?

Known Dependencies:

• Workspaces table must exist
• Users table must exist for created_by reference
• Encryption key management system must be in place

Technical Constraints:

Out of scope: Frontend UI changes (track separately). Focus on schema design and documentation.

Current Blockers:

None identified (update as work progresses)

Risk Assessment & Mitigations:

Security risks with encryption; use industry-standard encryption (AES-256). Ensure proper RLS policies for multi-tenant isolation. Consider key rotation strategy.

Resource Constraints:

• Deadline: Feb 5–17
• Effort Estimate: M (Medium - 3-5 days)

---

💡 Layer 4: Solution Generation

How should this be implemented?

Solution Approach:

Design a comprehensive workspace_providers table schema that:

1. Supports multiple provider types (LLM, Tenderly, RPC)
2. Implements encryption for sensitive data (API keys)
3. Enforces multi-tenant isolation via RLS policies
4. Supports provider metadata and configuration
5. Includes proper indexes for performance
6. Follows Supabase best practices

Design Considerations:

• Follow established patterns from .cursor/skills/
• Maintain consistency with existing codebase
• Consider scalability and maintainability
• Ensure proper security and encryption
• Plan for testing and validation
• Align with multi-tenant workspace model from Business Model
• Consider key rotation and encryption key management
• Design for extensibility (new provider types)

Acceptance Criteria (Solution Validation):

• Schema design document completed
• SQL migration script created
• RLS policies defined and tested
• Encryption strategy documented
• Indexes designed for performance
• Example provider configurations documented
• Schema reviewed and approved
• ADR created for design decisions
• Migration tested in development environment

---

📋 Layer 5: Execution Planning

What are the concrete steps?

Implementation Steps:

1. Review existing workspace and user schemas
2. Design workspace_providers table structure
3. Design encryption strategy for sensitive data
4. Design RLS policies for multi-tenant isolation
5. Create SQL migration script
6. Document provider configuration formats
7. Create ADR for design decisions
8. Review schema with team
9. Test migration in development environment
10. Update documentation (README, runbook, in-app help, etc.)

Environment Setup:
Repos / Services:

• Backend repo: hyperagent/services/orchestrator/
• Infra / IaC repo: hyperagent/infra/
• Database: Supabase project

Required Environment Variables:

• DATABASE_URL= (get from internal vault)
• SUPABASE_URL= (get from internal vault)
• SUPABASE_SERVICE_ROLE_KEY= (get from internal vault)
• ENCRYPTION_KEY= (get from internal vault)

Access & Credentials:

• API keys: Internal vault (1Password / Doppler)
• Access request: Contact @devops or project lead

---

✅ Layer 6: Output Formatting & Validation

How do we ensure quality delivery?

Ownership & Collaboration:

• Owner: @JustineDevs
• Reviewer: @ArhonJay
• Access Request: @JustineDevs or @ArhonJay
• Deadline: Feb 5–17
• Communication: Daily stand-up updates, GitHub issue comments

Quality Gates:

• Code follows project style guide
• Schema design follows best practices
• Security review completed
• Documentation updated (README, code comments, ADRs)
• Meets all acceptance criteria
• Migration script tested

Review Checklist:

• Schema design reviewed by @ArhonJay
• Security review completed
• RLS policies verified
• Performance indexes validated
• Migration script tested

Delivery Status:

• Initial Status: To Do
• Progress Tracking: Use issue comments for updates
• Sign-off: Approved by @Hyperionkit on 2026-02-06
• PR Link: [Link to merged PR(s)]

Related Issues:

• Implement workspace provider resolver (resolve LLM keys, Tenderly, RPC from workspace_providers table) #274: Implement workspace provider resolver
• Implement Workspace Settings UI (Providers tab: LLM keys, Tenderly, RPC endpoints) #275: Implement Workspace Settings UI
• Implement TS SDK workspace provider methods (configureProvider, getProviders, updateProvider) #287: Implement TS SDK workspace provider methods

Documentation References:

• Platform Blueprint
• Scope Definition
• Execution Strategy
• Business Model
• Database Schema Design
• Project Phases