Organization Model Enhancements & Registration Workflow

[Josephrp]

Type: Feature
Priority: P0 (Critical)
Labels: feature, backend, database, blockchain
Epic: #XXX (Epic: Complete Remaining Features)
Estimated Effort: 4-6 weeks

---

Description

Enhance Organization model with full registration fields and implement automated organization registration and blockchain deployment workflow.

Current State:

• ✅ Basic Organization model exists (name, slug, is_active)
• ✅ OrganizationBlockchainDeployment model exists (basic deployment tracking)
• ✅ Organization selection in signup flow exists
• ❌ Missing: legal_name, registration_number, tax_id, LEI, blockchain config fields
• ❌ Missing: Organization registration and approval workflow
• ❌ Missing: Automated blockchain deployment (private chain, sidechain, L2)
• ❌ Missing: Cross-chain communication service

Target State:

• Complete organization model with all registration fields
• Organization registration and approval workflow
• Automated blockchain deployment
• Cross-chain messaging service

Related Plan

dev/ORGANIZATION_IMPLEMENTATION_ASSESSMENT.md - Detailed assessment

Sub-Tasks

Database Models

• Enhance Organization Model (app/db/models.py)

  • Add legal_name (EncryptedString)
  • Add registration_number (EncryptedString, unique)
  • Add tax_id (EncryptedString)
  • Add lei (EncryptedString, unique)
  • Add industry, country, website, email fields
  • Add blockchain_type, blockchain_network, blockchain_rpc_url, blockchain_chain_id
  • Add blockchain_contract_addresses (JSONB)
  • Add bridge_contract_address, bridge_status
  • Add status, registration_date, approved_by, approved_at
  • Add subscription_tier, subscription_expires_at
  • Add metadata (JSONB)
  • Create Alembic migration

• Enhance OrganizationBlockchainDeployment Model

  • Add network_name, rpc_url (EncryptedString)
  • Add notarization_contract, token_contract, payment_router_contract, bridge_contract
  • Add status, deployed_at, deployed_by, deployment_metadata
  • Add updated_at field
  • Create Alembic migration

Backend Services

• Enhance OrganizationService (app/services/organization_service.py)

  • register_organization() - Full registration with all fields
  • approve_organization() - Approval workflow with blockchain deployment
  • deploy_organization_blockchain() - Automated blockchain deployment
  • _deploy_private_chain() - Private chain deployment logic
  • _deploy_sidechain() - Sidechain deployment logic
  • _deploy_l2() - L2 deployment logic
  • _deploy_bridge_contract() - Bridge contract deployment

• Create BlockchainRouterService (app/services/blockchain_router_service.py)

  • get_user_blockchain() - Get blockchain config for user
  • get_web3_connection() - Get/cache Web3 connections per organization
  • route_notarization() - Route notarization to org blockchain
  • _notarize_on_org_blockchain() - Org blockchain notarization
  • _notarize_on_main_chain() - Main chain notarization fallback

• Create CrossChainService (app/services/cross_chain_service.py)

  • send_cross_chain_message() - Send messages between org and main chain
  • _send_via_bridge() - Bridge integration
  • _get_chain_id() - Chain ID resolution

API Endpoints

• Update Organization API (app/api/organization_routes.py)
  • POST /api/organizations/register - Register new organization
  • POST /api/organizations/{id}/approve - Approve organization (admin)
  • POST /api/organizations/{id}/deploy-blockchain - Deploy blockchain

Frontend

• Update OrganizationSelectionStep (client/src/components/SignupFlow.tsx)
  • Add organization registration form with all fields
  • Add validation for required fields
  • Show registration status

Acceptance Criteria

1. ✅ Organization model has all registration fields
2. ✅ Organization registration workflow complete
3. ✅ Automated blockchain deployment working
4. ✅ Cross-chain messaging service operational
5. ✅ Blockchain router routes to organization blockchains
6. ✅ Organization approval workflow functional

Dependencies

• BlockchainService (✅ Already implemented)
• CrossChainBridge contract (✅ Already implemented)
• Organization signup flow (✅ Already implemented)

Testing

• Test organization registration
• Test organization approval
• Test blockchain deployment
• Test cross-chain messaging
• Test blockchain routing

---

Created: 2026-01-26
Status: Open