FoldDB Architecture

Overview

FoldDB combines schema-based data management, trust-based access control, and Lightning Network micropayments. The system uses immutable data storage with atomic operations and provides secure data access through public key authentication and trust distance calculations.

Core Components

System Architecture

graph TD
    subgraph Core[Core System]
        F[FoldDB] --> SC[SchemaCore]
        F --> PM[PermissionManager]
        F --> PY[PaymentManager]
        F --> AM[AtomManager]
    end
    subgraph Schema[Schema System]
        SC --> VM[ValidationManager]
        VM --> TM[TransformManager]
    end
    subgraph Security[Security Layer]
        PM --> TD[TrustDistance]
        PM --> PW[PermissionWrapper]
        PY --> LN[LightningNetwork]
    end
    subgraph Storage[Storage Layer]
        AM --> AT[Atoms]
        AM --> AR[AtomRefs]
        AT --> SL[Sled DB]
    end

System Components

1. Core System (FoldDB)

• Main Coordinator
  • Manages schema operations
  • Coordinates permissions
  • Processes payments
  • Handles data storage
• Integration Layer
  • Synchronizes components
  • Handles errors
  • Manages state
  • Cleans up resources

2. Schema System

classDiagram
    class SchemaCore {
        -schemas: Mutex<Map>
        -schemas_dir: PathBuf
        +load_schema()
        +unload_schema()
        +get_schema()
        +list_schemas()
        +schema_exists()
        +load_schemas_from_disk()
        +map_fields()
        +interpret_schema()
        +load_schema_from_json()
        +load_schema_from_file()
    }
    class ValidationManager {
        +checkTypes()
        +validateConstraints()
        +verifyPermissions()
    }
    SchemaCore --> ValidationManager

• JSON Schema Processing
  • Parses schema definitions
  • Validates fields
  • Checks types
  • Tracks relationships
• Transform Pipeline
  • Transforms schemas
  • Maps fields
  • Manages versions
  • Recovers from errors

3. Permission System

classDiagram
    class PermissionManager {
        -trustCalculator: TrustDistance
        -paymentVerifier: PaymentManager
        +validateAccess()
        +calculateTrust()
        +verifyPayment()
    }
    class TrustDistance {
        +calculate()
        +updateRelationships()
    }
    class PaymentManager {
        +verifyPayment()
        +createHoldInvoice()
    }
    PermissionManager --> TrustDistance
    PermissionManager --> PaymentManager

• Access Control
  • Calculates trust distance
  • Verifies permissions
  • Checks payment requirements
  • Logs access

4. Payment System

• Lightning Network Integration
  • Processes payments
  • Manages hold invoices
  • Calculates fees
  • Verifies transactions
• Trust-Based Pricing
  • Scales fees dynamically
  • Applies trust distance factors
  • Calculates operation costs
  • Tracks payment state

5. Storage System

classDiagram
    class AtomManager {
        +store()
        +retrieve()
        +update()
        +validateVersion()
    }
    class Atom {
        +content: any
        +metadata: Object
        +schema: SchemaRef
        +permissions: PermissionData
    }
    class AtomRef {
        -currentVersion: Atom
        +getLatest()
        +updatePointer()
    }
    AtomManager --> Atom
    AtomManager --> AtomRef

• Immutable Storage
  • Performs atomic operations
  • Tracks versions
  • Manages metadata
  • Recovers from errors

Data Flow

Operation Flow

sequenceDiagram
    participant C as Client
    participant F as FoldDB
    participant S as SchemaCore
    participant P as PermissionManager
    participant Y as PaymentManager
    participant A as AtomManager
    
    C->>F: Request
    F->>S: Validate Schema
    S-->>F: Schema Valid
    F->>P: Check Permissions
    P->>Y: Verify Payment
    Y-->>P: Payment Valid
    P-->>F: Access Granted
    F->>A: Store Data
    A-->>F: Success
    F-->>C: Response

Integration Patterns

1. Schema-Permission Integration

• Field-level permissions in schemas
• Trust distance configurations
• Payment requirements
• Access control rules

2. Permission-Payment Integration

• Trust-based pricing
• Payment verification
• Access control
• Transaction tracking

3. Storage-Schema Integration

• Schema validation
• Version management
• Transformation tracking
• Error handling

Error Handling

Recovery System

flowchart TD
    E[Error Detected] --> C[Categorize Error]
    C --> V[Validation Error]
    C --> P[Permission Error]
    C --> T[Transaction Error]
    C --> S[Storage Error]
    
    V --> VR[Retry Validation]
    P --> PR[Recalculate Permissions]
    T --> TR[Verify Transaction]
    S --> SR[Storage Recovery]
    
    VR --> R[Recovery Action]
    PR --> R
    TR --> R
    SR --> R
    
    R --> Success[Success]
    R --> Fallback[Fallback Action]
    
    Success --> Complete[Operation Complete]
    Fallback --> Notify[Notify System]

Error Categories

1. Validation Errors

   • Schema validation failures
   • Type mismatches
   • Constraint violations
   • Transform errors

2. Permission Errors

   • Trust calculation failures
   • Access denied
   • Invalid permissions
   • Payment required

3. Payment Errors

   • Payment verification failed
   • Invoice creation error
   • Transaction timeout
   • Invalid payment state

4. Storage Errors

   • Version conflicts
   • Write failures
   • Read failures
   • Consistency issues

Best Practices

1. Development Guidelines

• Use atomic operations
• Validate schemas early
• Check permissions before operations
• Verify payments upfront
• Handle errors gracefully
• Maintain clean version history

2. Performance Optimization

• Cache validated schemas
• Optimize trust calculations
• Batch similar operations
• Use efficient queries
• Monitor resource usage
• Profile critical paths

3. Security Considerations

• Validate all inputs
• Enforce permissions strictly
• Verify payments completely
• Monitor access patterns
• Track error rates
• Audit system usage

4. Maintenance

• Review schemas regularly
• Audit trust relationships
• Monitor payment system
• Optimize storage
• Analyze error patterns
• Tune performance

Extension Points

1. Schema Extensions

• Custom validators
• Transform pipelines
• Type handlers
• Constraint checkers

2. Permission Extensions

• Trust calculators
• Access policies
• Payment integrations
• Audit systems

3. Storage Extensions

• Backend adapters
• Cache strategies
• Index optimizers
• Recovery handlers