Subsidiary Model Documentation

Overview

The Subsidiary model represents organizational sub-units within an Entity in the CODITECT platform. It enables multi-regional operations, decentralized management, and hierarchical organizational structures. Subsidiaries inherit their parent Entity's tenant context while maintaining independent operational control within their designated regions.

Model Structure

Core Fields

Field	Type	Description	Constraints
subsidiary_id	UUID	Unique subsidiary identifier	Primary key, auto-generated
entity_id	UUID	Parent entity	Foreign key to Entity
name	String	Subsidiary name	Required, human-readable
code	String	Unique subsidiary code	Required, uppercase convention
region	String	Geographic region	Required (e.g., "Europe", "Asia-Pacific")
status	SubsidiaryStatus (Enum)	Operational status	Required
manager_id	UUID	Subsidiary manager	Foreign key to User
created_at	DateTime	Creation timestamp	Auto-set
updated_at	DateTime	Last modification	Auto-updated

SubsidiaryStatus Enum

enum SubsidiaryStatus {
    Active,     // Fully operational
    Inactive,   // Temporarily closed
    Suspended   // Compliance or legal hold
}

Example Structures

Regional Subsidiary

{
  "subsidiary_id": "550e8400-e29b-41d4-a716-446655440000",
  "entity_id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "CODITECT Europe GmbH",
  "code": "CODI-EU",
  "region": "Europe",
  "status": "Active",
  "manager_id": "789e0123-e89b-12d3-a456-426614174000",
  "created_at": "2025-01-15T10:00:00Z",
  "updated_at": "2025-08-29T14:30:00Z"
}

Product Division Subsidiary

{
  "subsidiary_id": "660e8400-e29b-41d4-a716-446655440000",
  "entity_id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "CODITECT Labs",
  "code": "CODI-LABS",
  "region": "Global",
  "status": "Active",
  "manager_id": "890e1234-e89b-12d3-a456-426614174000",
  "created_at": "2025-03-01T08:00:00Z",
  "updated_at": "2025-08-29T16:45:00Z"
}

Acquired Company Integration

{
  "subsidiary_id": "770e8400-e29b-41d4-a716-446655440000",
  "entity_id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "DevTools Pro (A CODITECT Company)",
  "code": "DEVTOOLS-PRO",
  "region": "North America",
  "status": "Active",
  "manager_id": "901e2345-e89b-12d3-a456-426614174000",
  "created_at": "2025-06-01T00:00:00Z",
  "updated_at": "2025-08-29T09:15:00Z"
}

Database Schema

Primary Storage Pattern

Key: /{entity_id}/subsidiaries/{subsidiary_id}
Value: JSON serialized Subsidiary object

Secondary Indexes

# Subsidiaries by region
/{entity_id}/subsidiaries_by_region/{region} -> [subsidiary_ids]

# Subsidiaries by status
/{entity_id}/subsidiaries_by_status/{status} -> [subsidiary_ids]

# Subsidiaries by manager
/{entity_id}/subsidiaries_by_manager/{manager_id} -> [subsidiary_ids]

# Subsidiary by code (unique lookup)
/{entity_id}/subsidiary_by_code/{code} -> subsidiary_id

Organizational Patterns

Geographic Distribution

Entity: CODITECT Global
├── CODI-NA (North America)
│   ├── CODI-US (United States)
│   ├── CODI-CA (Canada)
│   └── CODI-MX (Mexico)
├── CODI-EU (Europe)
│   ├── CODI-UK (United Kingdom)
│   ├── CODI-DE (Germany)
│   └── CODI-FR (France)
└── CODI-APAC (Asia-Pacific)
    ├── CODI-JP (Japan)
    ├── CODI-AU (Australia)
    └── CODI-SG (Singapore)

Functional Division

Entity: TechCorp
├── TECH-DEV (Development Division)
├── TECH-SALES (Sales Division)
├── TECH-SUPPORT (Support Division)
└── TECH-RESEARCH (R&D Division)

Hybrid Structure

Entity: GlobalSoft
├── Region-based
│   ├── GS-AMERICAS
│   └── GS-EMEA
└── Product-based
    ├── GS-CLOUD
    └── GS-ENTERPRISE

Extended Metadata (Implementation Pattern)

While the current model is simple, real-world usage often requires additional metadata stored in the Entity or separate tables:

Financial Information

{
  "subsidiary_financial": {
    "subsidiary_id": "550e8400-e29b-41d4-a716-446655440000",
    "fiscal_year": "2025",
    "revenue_target": 10000000.00,
    "cost_center": "CC-EU-001",
    "tax_id": "DE123456789",
    "currency": "EUR",
    "bank_accounts": [...]
  }
}

Compliance Data

{
  "subsidiary_compliance": {
    "subsidiary_id": "550e8400-e29b-41d4-a716-446655440000",
    "licenses": ["ISO-27001", "SOC2-Type2"],
    "regulatory_region": "EU",
    "data_residency": "eu-central-1",
    "gdpr_representative": "legal@coditect.eu"
  }
}

Operational Metrics

{
  "subsidiary_metrics": {
    "subsidiary_id": "550e8400-e29b-41d4-a716-446655440000",
    "employee_count": 150,
    "active_projects": 45,
    "monthly_api_calls": 12500000,
    "storage_usage_gb": 2500
  }
}

Related Code

Source Files

• Model: /src/models/subsidiary.rs
• Repository: /src/db/repositories/subsidiary_repository.rs
• API Handler: /src/api/handlers/subsidiary_handlers.rs
• Tests: /src/models/tests/subsidiary_tests.rs

Key Methods

impl Subsidiary {
    fn new(
        entity_id: Uuid,
        name: String,
        code: String,
        region: String,
        manager_id: Uuid
    ) -> Self
    
    fn activate(&mut self)
    fn suspend(&mut self, reason: String)
    fn change_manager(&mut self, new_manager_id: Uuid)
}

impl SubsidiaryRepository {
    async fn create(&self, subsidiary: &Subsidiary) -> Result<()>
    async fn get_by_id(&self, entity_id: &Uuid, subsidiary_id: &Uuid) -> Result<Option<Subsidiary>>
    async fn get_by_code(&self, entity_id: &Uuid, code: &str) -> Result<Option<Subsidiary>>
    async fn list_by_entity(&self, entity_id: &Uuid) -> Result<Vec<Subsidiary>>
    async fn list_by_region(&self, entity_id: &Uuid, region: &str) -> Result<Vec<Subsidiary>>
}

API Endpoints

Subsidiary Management

• POST /api/entities/{entity_id}/subsidiaries - Create subsidiary
• GET /api/entities/{entity_id}/subsidiaries - List subsidiaries
• GET /api/subsidiaries/{subsidiary_id} - Get subsidiary details
• PUT /api/subsidiaries/{subsidiary_id} - Update subsidiary
• DELETE /api/subsidiaries/{subsidiary_id} - Archive subsidiary

Operational Endpoints

• PUT /api/subsidiaries/{subsidiary_id}/status - Change status
• PUT /api/subsidiaries/{subsidiary_id}/manager - Change manager
• GET /api/subsidiaries/{subsidiary_id}/metrics - Get metrics

Reporting

• GET /api/entities/{entity_id}/subsidiaries/summary - Overview
• GET /api/subsidiaries/{subsidiary_id}/performance - Performance metrics

Business Rules

Creation Rules

1. Unique Code: Code must be unique within entity
2. Valid Region: Must be from approved region list
3. Active Manager: Manager must be active user
4. Parent Entity: Entity must be active
5. Naming Convention: Follow entity naming standards

Operational Rules

1. Status Changes: Require appropriate permissions
2. Manager Assignment: Must be employee of entity
3. Suspension: Requires reason and approval
4. Deletion: Soft delete only, maintain audit trail

Access Control

1. Entity Admin: Full access to all subsidiaries
2. Subsidiary Manager: Full access to own subsidiary
3. Regional Manager: Read access to region
4. Users: Access based on subsidiary assignment

Use Cases

Multi-National Operations

// Create regional subsidiary
let eu_subsidiary = Subsidiary::new(
    entity_id,
    "CODITECT Europe GmbH".to_string(),
    "CODI-EU".to_string(),
    "Europe".to_string(),
    eu_manager_id
);

// Set region-specific configuration
subsidiary_config.set_currency("EUR");
subsidiary_config.set_timezone("Europe/Berlin");
subsidiary_config.set_language("de-DE");

Franchise Model

// Create franchise subsidiary
let franchise = Subsidiary::new(
    franchisor_entity_id,
    "CODITECT Denver".to_string(),
    "CODI-DEN".to_string(),
    "North America".to_string(),
    franchise_owner_id
);

// Apply franchise rules
franchise_rules.set_revenue_share(0.15);
franchise_rules.set_brand_fee(5000.00);

Acquisition Integration

// Integrate acquired company
let acquired = Subsidiary::new(
    parent_entity_id,
    "InnovateTech (A CODITECT Company)".to_string(),
    "INNOVATE".to_string(),
    "Global".to_string(),
    retained_ceo_id
);

// Maintain separate operations
acquired_config.maintain_existing_systems(true);
acquired_config.gradual_integration_months(24);

Integration Points

With Entity Model

• Inherits tenant context
• Shares configuration
• Consolidated reporting
• Unified billing

With User Model

• Manager assignment
• Access control
• Approval workflows
• Communication channels

With Project Model

• Subsidiary-specific projects
• Resource allocation
• Budget tracking
• Performance metrics

Performance Considerations

Query Optimization

• Index on frequently queried fields
• Denormalize region for fast lookups
• Cache subsidiary metadata
• Batch operations for bulk updates

Data Distribution

• Partition by entity_id
• Regional data locality
• Read replicas for reporting
• Archive inactive subsidiaries

Security Considerations

Data Isolation

• Tenant-level isolation maintained
• Subsidiary data segregation
• Regional compliance requirements
• Cross-subsidiary access control

Audit Requirements

• All changes logged
• Manager change history
• Status change reasons
• Access audit trail

Future Enhancements

Advanced Features

1. Hierarchical Subsidiaries: Multi-level subsidiary structures
2. Virtual Subsidiaries: Temporary project-based units
3. Joint Ventures: Shared subsidiary ownership
4. Dynamic Regions: Custom region definitions

Integration Capabilities

1. ERP Integration: SAP, Oracle, etc.
2. Financial Systems: QuickBooks, Xero
3. HR Systems: Workday, BambooHR
4. Compliance Tools: Regional specific

Analytics Enhancements

1. Performance Dashboards: Real-time metrics
2. Comparative Analysis: Cross-subsidiary benchmarking
3. Predictive Analytics: Growth forecasting
4. Cost Optimization: Resource allocation AI

Automation

1. Auto-scaling: Based on workload
2. Compliance Monitoring: Automated checks
3. Report Generation: Scheduled reports
4. Alert System: Threshold-based notifications

---

Last Updated: 2025-08-29 Version: 1.0