Case Study - Enterprise configuration management platform: Multi-platform React application with visual workflow editors and hexagonal architecture

Overview

FlowConfig applications rely on extensive configuration files—workflows (BPMN), case management (CMMN), decision tables (DMN), forms, validation rules, and document templates. Originally, customers and internal configurators edited raw XML and JSON files manually. This approach was:

• Error-prone: One misplaced bracket broke entire configurations
• Slow: Finding and editing specific rules across thousands of lines of XML
• Requires expertise: Non-technical users couldn't configure applications
• Version control challenges: Merge conflicts in large XML files
• No validation feedback: Errors discovered only at runtime

The solution was clear: build a sophisticated configuration management platform with visual editors abstracting complexity, real-time validation, Git integration, and support for both cloud-based and offline desktop workflows.

FlowConfig Pro addresses these challenges with:

1. Visual editors for workflows (BPMN), cases (CMMN), decisions (DMN)
2. Drag-and-drop form builder with instant preview
3. Rich text editor for document templates
4. Monaco Editor (VS Code editor) for power users needing raw XML/JSON access
5. Real-time validation with detailed error messages
6. Git integration for version control
7. Multi-tenant architecture supporting multiple applications
8. Cloud-based web application (AWS) for anywhere access
9. Electron desktop application for offline workflows and air-gapped environments
10. Comprehensive testing ensuring reliability

What we did

Full-stack TypeScript architecture

The platform embraces TypeScript throughout for type safety and developer experience:

Frontend: React 18 + TypeScript 5.9: Modern React with hooks, context, and functional components. Vite 6.4 build tool replacing Create React App—significantly faster builds (60% improvement) and hot module replacement. TypeScript strict mode catches type errors at compile time. React Router DOM 6.30 for client-side routing with nested routes.

Backend: Node.js 22 + Express 5 + TypeScript: Express web framework with TypeScript migration (gradual conversion from JavaScript). Hexagonal Architecture (detailed below) ensures clean separation of concerns. Type-safe domain models and use cases. Express middleware for authentication, logging, and error handling.

Shared types: Generated TypeScript types from backend to frontend ensure API contract compliance. Changes to backend endpoints automatically reflect in frontend types. This prevents common bugs where frontend expects different response shapes than backend provides.

Result: Type safety across the entire stack reduces runtime errors significantly. IDE autocomplete accelerates development. Refactoring is safer—TypeScript catches breaking changes. New developers onboard faster with discoverable, type-documented APIs.

Hexagonal Architecture (Ports & Adapters)

The backend implements Hexagonal Architecture—a clean architecture pattern separating business logic from infrastructure:

Layer structure

Domain Layer (core): Business entities and rules—Configuration, Workflow, Form, Validation. No dependencies on frameworks or infrastructure. Pure TypeScript classes and interfaces. This layer contains the essential business logic independent of delivery mechanisms.

Application Layer: Use cases orchestrating domain logic—CreateConfiguration, ValidateWorkflow, PublishTemplate. Defines ports (interfaces) for external dependencies. Implements business workflows combining multiple domain entities. This layer answers "what does the system do?"

Primary Adapters (inbound): REST API routes receiving HTTP requests. Async message handlers consuming SQS messages. These adapters translate external requests into application use case calls. They handle HTTP-specific concerns (request parsing, response formatting, authentication) without business logic.

Secondary Adapters (outbound): Repositories for database access (MongoDB/DocumentDB). External service clients (GitHub API via Octokit, AWS services). These adapters implement the ports defined by application layer. They handle infrastructure concerns (database queries, HTTP calls, file I/O) without business logic.

Benefits realized

Testability: Business logic tests run without database, without external services—pure unit tests execute in milliseconds. Use case tests mock secondary adapters. Integration tests verify real adapter implementations. This multi-layer testing strategy catches different bug classes.

Maintainability: Clear boundaries between layers prevent coupling. Changes to database schema only affect repository adapters, not business logic. Switching from MongoDB to PostgreSQL would only require new repository implementations—domain and application layers unchanged.

Flexibility: Multiple primary adapters expose same use cases—REST API and async message handlers share business logic. Future GraphQL API would just add another primary adapter. Same business logic serves multiple interfaces.

Onboarding: New developers understand system by reading domain layer—entities and use cases document business requirements. They don't need to understand MongoDB queries or AWS SQS to grasp what the system does.

Evolution: Gradual TypeScript migration from JavaScript happened layer by layer. Domain entities first (most value, least dependencies). Then application use cases. Finally adapters. This incremental approach minimized risk.

Visual editors for complex configurations

The platform integrates specialized editors for different configuration types:

BPMN workflow editor (bpmn-js 8.10)

Visual editor for business process workflows—the core of FlowConfig applications:

• Drag-and-drop workflow modeling: Tasks, gateways, events, subprocesses
• BPMN 2.0 standard: Industry-standard workflow notation
• Properties panel: Configure task properties, conditions, assignments
• Validation: Real-time BPMN validation ensuring syntactic correctness
• Zoom and pan: Navigate large workflows with dozens of nodes
• Minimap: Overview of entire workflow for orientation

Use case: Customer configures claim processing workflow—initial review task, decision gateway checking claim amount (< $1000 auto-approve, >= $1000 requires manager approval), parallel subprocess for fraud check and document verification, final approval task. Previously required editing 500+ lines of XML. Now visual modeling in minutes.

CMMN case management editor (cmmn-js 0.20)

Visual editor for case management—flexible, knowledge-intensive workflows:

• Case model design: Stages, tasks, milestones, sentries
• Discretionary items: Optional tasks users can activate dynamically
• Entry/exit criteria: Conditions controlling stage lifecycle
• Human tasks: User-assigned tasks with roles and permissions

Use case: Customer service case management—initial triage stage, investigation tasks (optional depending on case type), resolution milestone, closure stage. Case workers decide dynamically which investigation tasks to activate based on case specifics. CMMN's flexibility models this better than rigid BPMN workflows.

DMN decision table editor (dmn-js 11.1)

Visual editor for business decision logic:

• Decision table: Rows for rules, columns for inputs/outputs
• Hit policies: First hit, collect all, priority-based
• Expression language: FEEL (Friendly Enough Expression Language)
• Testing: Test decision tables with sample inputs

Use case: Loan approval decisions—inputs (credit score, income, debt ratio), outputs (approve/deny, interest rate). Decision table with rules: credit score < 600 → deny, score 600-700 && debt ratio > 40% → deny, score > 700 → approve with tiered interest rates. Previously scattered across code. Now centralized, visible, editable by business analysts.

Monaco Editor (0.52)

VS Code editor embedded in the browser for power users:

• Syntax highlighting: XML, JSON, JavaScript with language-aware coloring
• IntelliSense: Autocomplete for configuration elements
• Error markers: Underline syntax errors inline
• Multi-cursor editing: Edit multiple locations simultaneously
• Find and replace: Regex support for bulk edits

Use case: Advanced users needing direct XML access—bulk find-replace operations, copy-paste from external sources, precise control over XML structure. The visual editors abstract 90% of use cases; Monaco Editor handles the remaining 10% requiring raw access.

TinyMCE rich text editor (6.3)

WYSIWYG editor for document templates:

• Rich formatting: Bold, italic, lists, tables, images
• Template variables: Insert placeholders for dynamic content
• HTML source editing: Switch between visual and source modes
• Spell checking: Integrated spell checker
• Custom toolbar: Configure available formatting options

Use case: Email and document templates with dynamic content—"Dear {{customer.name}}, your claim {{claim.id}} has been {{claim.status}}." Business users edit templates visually without HTML knowledge. Templates support rich formatting (bold headers, bullet lists, tables) while maintaining dynamic variable substitution.

React Query Builder (4.2)

Visual query builder for filter configurations:

• Drag-and-drop rules: Build complex filter conditions
• Field selection: Choose from available data fields
• Operator selection: Equals, contains, greater than, date ranges
• Compound conditions: AND/OR logic grouping
• JSON export: Export filter configuration as JSON

Use case: Configuring report filters—"Show claims where status = 'pending' AND (claim amount > $5000 OR priority = 'high') AND created date within last 30 days." Business analysts build these complex filters visually. The query builder generates JSON configuration consumed by backend reporting engine.

AWS cloud infrastructure

The platform runs on comprehensive AWS infrastructure:

Compute: ECS Fargate

Serverless container orchestration—no EC2 instances to manage:

• Task definition: 2 vCPU, 4GB RAM per container
• Desired count: 2 instances minimum for high availability
• Auto-scaling: Scale up under load (CPU > 70%)
• Blue-green deployment: Zero-downtime deployments via ECS service updates
• Health checks: ALB health checks ensure only healthy containers receive traffic
• Graceful shutdown: Containers finish in-flight requests before termination

Benefit: Fargate eliminates server management. Auto-scaling handles traffic spikes. High availability with multiple instances across availability zones. Cost-effective—pay only for container runtime, not idle EC2 instances.

Database: DocumentDB

MongoDB-compatible managed database:

• Instance class: db.r6g.large (2 vCPU, 16GB RAM)
• Storage: Auto-scaling from 10GB to 64TB
• Backup retention: 35 days for disaster recovery
• Encryption: At-rest encryption enabled
• Multi-AZ: Primary instance with read replica in different availability zone
• Monitoring: CloudWatch metrics for CPU, memory, connections, latency

Benefit: Managed database eliminates operational overhead—automated backups, patching, scaling. MongoDB compatibility allows using MongoDB drivers and tools. Multi-AZ ensures availability during failures. 35-day backup retention supports compliance requirements.

CDN: CloudFront

Global content delivery network for frontend assets:

• Price class: 100 (US, Canada, Europe)—optimizes cost for target markets
• Custom SSL certificate: HTTPS with custom domain
• Cache behaviors: Different caching for static assets (long TTL) vs API calls (no cache)
• Compression: Automatic gzip/brotli compression
• Origin failover: Secondary S3 bucket for high availability

Benefit: Fast load times globally—assets served from edge locations near users. HTTPS security. Reduced backend load—static assets cached at edge. Cost-effective—CloudFront cheaper than serving from origin.

Message queue: SQS

Asynchronous command processing for long-running operations:

• Long polling: 20-second wait reduces empty responses
• Visibility timeout: 30 seconds for message processing
• Dead letter queue: Failed messages move to DLQ for investigation
• FIFO option: Order-preserving queues where needed

Benefit: Decouples frontend from long-running operations. User initiates configuration validation → immediately receives acknowledgment → validation runs asynchronously → user notified on completion. This prevents request timeouts and improves perceived performance.

Monitoring: CloudWatch + X-Ray

Comprehensive observability:

• Log groups: Backend logs (30 days), HTML validator (7 days), OTEL collector (7 days)
• Metrics: CPU, memory, request count, latency, error rate
• Alarms: Database CPU > 80% triggers SNS notification
• X-Ray tracing: Distributed tracing for request flow across services
• Dashboards: Custom dashboards for real-time monitoring

Benefit: Rapid troubleshooting—X-Ray traces show exactly where requests slow down (database query? external API call?). CloudWatch Logs Insights queries logs across all instances. Alarms notify team before users experience problems.

Electron desktop application

Cross-platform desktop application for offline workflows:

Multi-window support: Tabbed interface with windows—users open multiple configurations simultaneously. Each tab can be torn off into separate window. State persists across restarts.

Embedded backend: Node.js backend runs locally within Electron app. No server required—fully offline workflow. Uses local file system instead of cloud database.

File system watching: Chokidar monitors configuration directory for changes. External edits (IDE, text editor) automatically reload in FlowConfig Pro. Enables hybrid workflow—visual editors for structure, IDE for detailed customization.

Auto-updates: Electron auto-updater checks for new versions on launch. Users notified of updates—download and install with one click. Ensures users stay current with latest features and fixes.

Code signing: macOS and Windows code signing prevents "untrusted application" warnings. Critical for enterprise customers with strict security policies.

Build targets: DMG and ZIP for macOS, Squirrel installer for Windows, DEB and RPM for Linux. Single codebase deploys to all platforms.

Local Git integration: isomorphic-git enables Git operations in desktop app—commit, push, pull without external Git installation. Users version control configurations directly from FlowConfig Pro.

Use case: Government customer with air-gapped environment (no internet access for security). Desktop app installed from USB drive. Configurations created and tested entirely offline. When approved, configurations exported to USB drive → moved to connected environment → pushed to Git repository. This workflow impossible with cloud-only solution.

Git integration and version control

Configuration version control via GitHub integration:

GitHub App authentication: OAuth App with repository access permissions. Users authorize FlowConfig Pro → can access private repositories. Secure token handling with automatic refresh.

Git operations via isomorphic-git: Pure JavaScript Git implementation—no native Git required. Commit configuration changes with commit messages. Push to remote repository. Pull latest changes. View commit history.

SCM service abstraction: Repository pattern abstracts Git operations—interface defines commit(), push(), pull() methods. GitHub implementation uses Octokit API. Future GitLab/Bitbucket support only requires new adapter implementing same interface.

Conflict resolution: Visual merge tool for configuration conflicts. Side-by-side comparison with visual editors showing differences. Users choose which version to keep or merge manually.

Branching workflow: Create feature branches for experimental configurations. Test thoroughly. Merge to main branch when validated. This mirrors modern software development workflow, applied to configurations.

Benefit: Configuration history is fully auditable—who changed what, when, why (commit messages). Rollback to previous versions if changes cause issues. Branching enables safe experimentation without affecting production configurations. Teams collaborate on configurations using pull request workflows.

Authentication and multi-tenant architecture

Enterprise-grade security and tenant isolation:

Auth0 integration: OpenID Connect authentication—users log in via Auth0 (supports SAML, Google, Microsoft, etc.). express-openid-connect middleware handles authentication flow. JWT bearer tokens validate API requests (express-oauth2-jwt-bearer).

Multi-tenant isolation: App-based tenancy—each application (tenant) has isolated configuration space. Users assigned to one or more applications. Database queries automatically filter by application ID. Users cannot access configurations from applications they don't belong to.

Role-based permissions: Admin, configurator, viewer roles with different capabilities. Admins manage users and permissions. Configurators create and modify configurations. Viewers read-only access. Enforced at API level—use cases check user permissions before executing.

Session management: Server-side sessions with secure cookies. Session expiry after inactivity. Refresh token rotation for security.

Secrets management: AWS Systems Manager Parameter Store stores sensitive configuration (database credentials, API keys, Auth0 secrets). Environment variables reference Parameter Store paths. Secrets never committed to code repository.

Benefit: Enterprise customers require strong authentication—SAML integration with corporate SSO. Multi-tenancy enables SaaS model—single deployment serves multiple customers with data isolation. Role-based permissions implement least-privilege principle. Parameter Store centralizes secrets management with encryption and access control.

Comprehensive testing strategy

Multi-layer testing ensures reliability:

Unit tests: Vitest (frontend) and Jest (backend) for component/function tests. Domain layer tests verify business rules—no database, no external services. Fast execution (1000+ tests in seconds). High coverage (>80%) on critical paths.

Integration tests: Jest tests with real external services—actual DocumentDB database, real GitHub API calls (test account). Verify adapters correctly implement ports. Require VPN access and permissions (slower, run less frequently).

E2E tests: Cypress tests full user workflows—login, create workflow, configure form, save, validate. Run against real application in test environment. Headless execution in CI pipeline. Screenshot and video capture on failures.

Component tests: Cypress Component Testing for React components in isolation. Faster than E2E (no full app startup). Test component edge cases—empty states, error states, loading states. MSW mocks API calls.

Visual regression: Storybook snapshots detect unintended UI changes. Every component has Storybook stories demonstrating variants. Automated screenshot comparison catches visual bugs.

Desktop app tests: Playwright tests Electron application—window management, file operations, offline workflows. Test auto-update flow. Verify code signing.

Load testing: K6 load tests simulate concurrent users—performance under load, identify bottlenecks. Verify auto-scaling triggers correctly.

Mutation testing: Stryker mutates code (change operators, remove statements)—verify tests catch mutants. Measures test quality, not just coverage.

Result: Comprehensive testing catches bugs early. Developers refactor confidently—tests verify behavior unchanged. CI pipeline blocks broken code from merging. Production deployment confidence is high.

CI/CD pipeline and automation

Comprehensive Jenkins pipeline automates quality gates:

Parallel build stages: Frontend, backend, and desktop builds run simultaneously—install dependencies, lint, test, build. Reduces pipeline time from 45 minutes (sequential) to 15 minutes (parallel).

Quality gates: Linting must pass (ESLint with strict rules). Prettier formatting check must pass. Unit tests must pass. E2E tests must pass. Coverage threshold must be met. Any failure blocks merge and deployment.

Automated deployment: Master branch merges trigger automatic deployment—build Docker containers, push to registry, update ECS service (blue-green deployment), invalidate CloudFront cache. Zero manual steps from commit to production.

Translation checks: i18next-parser verifies all UI strings have translations. Missing translations fail build. Ensures internationalization completeness.

Notifications: Office 365 webhook sends build status to team channel—success, failure, deployment complete. Team immediately aware of build issues.

RenovateBot: Automated dependency updates—RenovateBot creates pull requests for dependency updates. CI pipeline tests updates automatically. Team reviews and merges. Keeps dependencies current with minimal effort.

Docker optimization: Multi-stage Docker builds minimize image size. Development dependencies excluded from production images. Image layers cached for faster builds. Production images <500MB.

Result: Automated CI/CD reduces deployment friction. Developers commit to master → 15 minutes later changes are live. Quality gates maintain code quality without manual review burden. RenovateBot keeps dependencies current, preventing security vulnerabilities from outdated packages.

Results and impact

FlowConfig Pro transformed configuration management:

Configuration efficiency: Configuration time decreased 70%. Previously, creating complex workflow with 50 steps, 10 decision points, 30 form fields required 2 weeks of XML editing and testing. Now completed in 3 days with visual editors. Form builder alone reduced form creation time 80%—drag fields, configure validation, see live preview. No XML editing.

Error reduction: Configuration errors dropped 85%. Real-time validation catches errors immediately—missing required properties, invalid references, syntax errors. Previously errors discovered during application testing—days after configuration. Now caught instantly. Production deployments without configuration errors increased from 60% to 95%.

Accessibility: Non-technical users now configure applications. Business analysts create decision tables without developer help. Customer success team modifies email templates without engineering involvement. This democratization of configuration reduced engineering backlog and accelerated customer implementations.

Offline workflows: Desktop app enabled workflows impossible with cloud-only solution. Government customers with air-gapped environments can configure FlowConfig applications. Field engineers configure systems at remote locations without internet. Offline capability expanded addressable market.

Version control adoption: Git integration brought software development best practices to configurations. Teams now use branching for experimental changes. Commit messages document why changes were made. Configuration history is auditable—compliance requirement for regulated industries. Rollback capability reduces risk of changes.

Developer velocity: Hexagonal architecture improved maintainability. Code organized by business capabilities, not technical layers. Adding features requires modifying use case and domain entities—adapters often unchanged. Test isolation (unit tests without database) accelerated test execution and debugging. New developers productive faster—architecture is self-documenting.

Infrastructure reliability: AWS infrastructure with multi-AZ deployment achieved 99.9% uptime. Auto-scaling handled traffic spikes without manual intervention. Blue-green deployments eliminated downtime during releases. CloudWatch alarms notified team of issues before customer impact.

Cost optimization: ECS Fargate reduced infrastructure costs 40% compared to previous EC2-based deployment. No idle server capacity. Auto-scaling reduced over-provisioning. CloudFront reduced bandwidth costs by caching static assets at edge. DocumentDB backups eliminated operational overhead of backup management.

Testing confidence: Comprehensive test suite enabled rapid iteration without fear of regressions. Developers refactored aggressively—tests verify behavior unchanged. Feature development velocity increased—less time debugging, more time building. Test suite catches integration issues in CI pipeline, not production.

Customer satisfaction: Configuration complexity was primary customer complaint. FlowConfig Pro addressed this directly. Customer satisfaction scores increased 35 points (NPS scale). Support tickets related to configuration issues dropped 60%. Customers self-serve configurations instead of requesting professional services.

Time to market: New customer implementations accelerated. Previously 3-6 months from contract signing to production (configuration complexity was bottleneck). Now 1-2 months. Faster implementations increased revenue recognition and improved cash flow.

Technical excellence

The project demonstrates modern full-stack development and architecture:

Clean architecture: Hexagonal Architecture with clear layer separation makes codebase maintainable and testable. Business logic isolated from infrastructure enables independent evolution. Use case pattern documents system capabilities. New features fit naturally into architecture.

Type safety: TypeScript throughout stack eliminates entire classes of bugs. Generated types from backend to frontend ensure API contract compliance. Refactoring is safe—compiler catches breaking changes. IDE support dramatically improves developer experience.

Specialized editors: Integration of best-in-class editors (bpmn-js, Monaco, TinyMCE) provides professional experience. No need to build custom editors from scratch. Standing on shoulders of giants—these editors are battle-tested in thousands of applications.

Cloud-native: AWS services (ECS Fargate, DocumentDB, CloudFront, SQS, CloudWatch) provide managed infrastructure eliminating operational overhead. Auto-scaling, automated backups, distributed tracing, multi-AZ deployment—enterprise capabilities without dedicated operations team.

Multi-platform: Single TypeScript codebase serves web application and Electron desktop app. React components shared between platforms. Backend logic shared via npm packages. Platform-specific code isolated to adapters. This code reuse accelerated desktop app development and ensures feature parity.

Observability: OpenTelemetry instrumentation provides detailed distributed tracing. X-Ray shows request flow across services—frontend, backend, database, external APIs. Winston structured logging enables CloudWatch Logs Insights queries. Comprehensive monitoring reduces mean time to resolution for production issues.

Developer experience: Vite provides instant hot module replacement. Storybook enables component-driven development. Comprehensive ESLint rules catch common mistakes. Prettier eliminates formatting debates. Great tooling makes development enjoyable and productive.

Security: Auth0 handles authentication complexities—OAuth flows, token management, refresh token rotation. JWT validation in API middleware prevents unauthorized access. Multi-tenant isolation prevents data leaks between applications. AWS Parameter Store secures secrets. Security built-in, not bolted on.

Testing culture: Multi-layer testing strategy catches different bug types—unit tests verify logic, integration tests verify external dependencies, E2E tests verify user workflows, visual regression tests catch UI bugs. High test coverage enables confident refactoring. Tests document expected behavior.

Continuous delivery: Automated CI/CD pipeline from commit to production enables rapid iteration. Quality gates maintain code quality. Blue-green deployment eliminates downtime. Automated dependency updates keep codebase current. DevOps practices integrated from day one.

FlowConfig Pro proves that sophisticated configuration management can be both powerful and accessible—visual editors for common cases, raw editors for edge cases, clean architecture for maintainability, comprehensive testing for reliability, and multi-platform support for flexibility.