Skip to main content

KZN Test App Documentation

Summary​

KZN Test App is a proof-of-concept application designed to explore and validate integration patterns between Salesforce and Xero accounting software. Built with modern cloud-native architecture, it serves as a test harness for experimenting with bidirectional sync workflows and data transformation patterns.

Project Overview​

The application consists of two main systems:

1. Salesforce-Xero Integration Test System​

A test application that explores how Salesforce-style entity management can integrate with Xero accounting:

  • Integration Test Documentation - Complete system overview
  • Technology Stack: React + TypeScript + Python Lambda + DynamoDB
  • Test Scenarios: Multi-company management, contract lifecycle, invoice automation
  • Integration Focus: Xero accounting software synchronization patterns

2. UI Component System​

A comprehensive design system built on atomic design principles:

  • UI Components - Design system documentation
  • Technology: shadcn/ui + Tailwind CSS + Storybook
  • Architecture: Atomic design with reusable components

System Architecture​

The application follows modern cloud-native principles:

Frontend (React SPA) → API Gateway → Lambda Functions → DynamoDB
                                         ↓
                                   Xero Integration

Core Components​

  • Frontend: React 18 with TypeScript and Vite
  • Backend: Serverless Python Lambda functions
  • Database: DynamoDB with single-table design
  • API: RESTful API via AWS API Gateway
  • Infrastructure: AWS CDK for infrastructure as code

Documentation Structure​

The project documentation is organized into comprehensive pillars:

1. API Documentation​

Complete API reference and integration guides:

2. Infrastructure​

AWS cloud infrastructure and deployment:

  • Serverless architecture with Lambda and DynamoDB
  • CDK infrastructure as code
  • Environment management and deployment guides
  • Monitoring and operational procedures

3. Features​

Business functionality and user workflows:

4. Architecture​

Technical design and system architecture:

  • System design patterns
  • Security architecture
  • Performance optimization
  • Integration strategies

5. UI System​

Component library and design system:

Getting Started​

Local Development​

  1. Prerequisites: Node.js 18+, Python 3.9+, AWS CLI
  2. Installation: npm install and ./run.sh setup
  3. Development: ./run.sh dev to start all services
  4. Documentation: Visit http://localhost:3250

Deployment​

  1. AWS Setup: Configure AWS credentials and CDK
  2. Infrastructure: Deploy with npm run backend:deploy
  3. Frontend: Build and deploy with npm run deploy:app
  4. Monitoring: Access CloudWatch dashboards

Key Features​

Business Management​

  • Multi-company Support: Manage multiple business entities
  • Customer Relationships: Comprehensive contact management
  • Contract Lifecycle: From creation to renewal
  • Financial Operations: Invoicing, payments, and reconciliation

Technical Capabilities​

  • Scalable Architecture: Serverless auto-scaling
  • Real-time Integration: Xero webhook processing
  • Type Safety: End-to-end TypeScript
  • API-First: OpenAPI specification driven

Developer Experience​

  • Hot Reloading: Fast development cycles
  • Component Library: Reusable UI components
  • Comprehensive Testing: Unit, integration, and E2E tests
  • Documentation: Living documentation with examples

Integration Capabilities​

Current Integrations​

  • Xero Accounting: Two-way sync for invoices and payments
  • Email Delivery: Automated invoice and notification sending

Planned Integrations​

  • Salesforce CRM: Contact and opportunity synchronization
  • Stripe Payments: Direct payment processing
  • DocuSign: Electronic contract signing
  • Power BI: Advanced analytics and reporting

Support and Resources​

Documentation​

Development​

  • Local Setup: Follow infrastructure deployment guides
  • Contributing: See development standards in architecture documentation
  • Issues: Use GitHub issue tracker for bug reports and feature requests

Project Status​

Current Version: 1.0.0 Status: Active Development Last Updated: June 2025 Maintenance: Actively maintained

The application is ready for production use with comprehensive testing, monitoring, and documentation.