Skip to content
VLN Logo VLN Documentation

PeraltaCC Architecture

PeraltaCC Architecture

PeraltaCC is built as a modular Node.js application leveraging Claude Flow v3 for automation, with integrated GitBook documentation and Git-based workflows.

Technology Stack

Core Runtime

  • Node.js ≥ 18.0.0
  • npm ≥ 8.0.0
  • TypeScript (for type safety)

Key Technologies

  • Claude Flow v3 - AI automation workflows
  • GitBook - Documentation platform (via Git Sync)
  • Git - Version control and proposal tracking
  • GitHub Actions - CI/CD automation

System Architecture

┌────────────────────────────────────────┐
│     PeraltaCC Application              │
│     (Node.js + Claude Flow v3)         │
├────────────────────────────────────────┤
│                                        │
│  Modules:                              │
│  ├─ Redistricting Engine               │
│  ├─ ERP Automation                     │
│  ├─ Proposal Manager                   │
│  ├─ GitBook Sync                       │
│  └─ Workflow Orchestrator              │
│                                        │
├────────────────────────────────────────┤
│  Data Layer                            │
│  ├─ JSON/YAML Configuration            │
│  ├─ Proposal Artifacts                 │
│  └─ Git Repository State               │
├────────────────────────────────────────┤
│  Documentation (GitBook)               │
│  ├─ docs/gitbook/ (Primary Source)     │
│  ├─ Git Sync (Automated)               │
│  └─ PDF Exports                        │
├────────────────────────────────────────┤
│  CI/CD Pipeline (GitHub Actions)       │
│  ├─ Quality Gate Validation            │
│  ├─ Linting & Tests                    │
│  └─ Deployment Automation              │
└────────────────────────────────────────┘

Core Modules

1. Redistricting Engine

Purpose: District boundary planning and optimization

Responsibilities:

  • Boundary calculation algorithms
  • Demographic analysis
  • Impact assessment
  • Optimization recommendations

Integration: Feeds data to proposal generation and ERP systems

2. ERP Automation

Purpose: Streamlined enterprise resource planning workflows

Capabilities:

  • Process automation
  • Workflow orchestration
  • Department coordination
  • Functional alignment

Integration: Consumes redistricting output, coordinates across departments

3. Proposal Manager

Purpose: Bid and proposal lifecycle management

Responsibilities:

  • Proposal artifact organization (Tasks 1-6)
  • Deliverable tracking
  • Version management
  • Quality gate enforcement

Integration: GitHub branches, GitBook documentation, CI/CD gates

4. GitBook Sync Integration

Purpose: Automated documentation management

Workflow:

  1. Canonical docs in docs/gitbook/
  2. Git Sync to GitBook space (automated)
  3. Manual editing in GitBook space
  4. Sync back to repository
  5. PDF exports generated

Features:

  • Bi-directional sync
  • Automatic versioning
  • PDF generation
  • Public/private visibility control

5. Workflow Orchestrator

Purpose: Claude Flow v3-based automation

Capabilities:

  • Multi-step process automation
  • Conditional branching
  • Error handling and recovery
  • Human-in-loop approvals

Data Flow

Proposal Development Workflow

GitHub Issue/Discussion
    ↓
Feature Branch Creation
    ↓
Proposal Development (Claude Flow)
    ↓
Artifact Creation (Tasks 1-6)
    ↓
Quality Gate Checks
    ├→ Linting
    ├→ Testing
    ├→ Documentation Validation
    └→ Governance Requirements
    ↓
PR Review & Approval
    ↓
GitBook Sync (Automated)
    ↓
PDF Generation & Distribution

Documentation Workflow

GitBook Space (Editor Editing)
    ↓
Git Sync (Automated Pull)
    ↓
Repository docs/gitbook/
    ↓
CI/CD Pipeline Validation
    ↓
PDF Export Generation
    ↓
Deployment & Distribution

Quality Gates & Governance

Branch Protection Rules

  • main - Production branch (requires PR + approval)
  • feature/gitbook - Documentation staging (requires validation)
  • Feature branches - Development (feature/*, fix/*, docs/*)

Quality Gate Validation

gates:
  - linting: ESLint, Prettier
  - testing: Unit and integration tests
  - documentation: Markdown validation, link checking
  - governance: Task checklists, certification tracking
  - security: Dependency scanning, secret detection

Submission Requirements

  • All tasks completed (1-6)
  • Quality gates passing
  • Documentation updated
  • Certifications attached
  • Review approvals

Integration Points

Claude Flow v3 Integration

  • Workflow automation for proposal generation
  • ERP process orchestration
  • Documentation generation
  • Quality gate enforcement

GitHub Integration

  • Repository hosting
  • PR/branch workflow
  • Actions for CI/CD
  • Issue tracking

GitBook Integration

  • Primary documentation source
  • Web-based editor access
  • PDF export capability
  • Public sharing options

Deployment Architecture

Development Environment

Local Machine
├─ Node.js + npm
├─ Git repository
├─ Claude Flow configuration
└─ Local documentation preview

Staging Environment

GitHub feature/gitbook branch
├─ GitBook space connected via Git Sync
├─ CI/CD validation
├─ Preview generation
└─ Quality gate enforcement

Production Environment

GitHub main branch
├─ Canonical proposal artifacts
├─ Published documentation
├─ PDF exports
└─ Distribution ready

Performance & Scalability

Current Approach

  • Node.js single process (suitable for current workload)
  • Git-based state management (infinite scalability)
  • GitBook handles documentation distribution
  • GitHub Actions for automation

Scaling Considerations

If automation load increases:

  • Implement job queuing (Bull, RabbitMQ)
  • Add background workers
  • Distribute Claude Flow tasks
  • Consider containerization (Docker)

Security Considerations

Data Protection

  • GitHub branch protection
  • GitBook access control
  • Secret management via GitHub Secrets
  • No sensitive data in proposals

Authentication

  • GitHub OAuth (built-in)
  • GitBook workspace permissions
  • Role-based access control

Compliance

  • Audit logging via Git history
  • Certification tracking
  • Quality gate enforcement
  • Documentation of approvals

Next Steps