Technology Stack & Architecture

Technology Stack & Architecture

Complete overview of the technologies, frameworks, and infrastructure that power iSu Technologies solutions.

---

🎯 Philosophy

Technology Selection Criteria

1. Production-Ready: Battle-tested in enterprise environments
2. Scalable: Handle growth from hundreds to millions of users
3. Modern: Current best practices, active communities
4. Maintainable: Clear documentation, good developer experience
5. Cost-Effective: Balance performance with operational costs
6. African Context: Work well with African internet infrastructure

---

🖥️ Frontend Stack

⚛️ React 18

▲ Next.js 14

📘 TypeScript

🎨 TailwindCSS

🐻 Zustand

React 18

Purpose: UI component framework Why We Chose It:

• Industry standard with massive ecosystem
• Component-based architecture for reusability
• Excellent performance with virtual DOM
• Strong TypeScript support
• Extensive library of third-party components

Use Cases:

• SACE Provider Intelligence dashboards
• ThriveSend B2B2G interface
• AssessFlow assessment interfaces
• AutoSlip web portal and admin interface

---

Next.js 14

Purpose: React framework with SSR/SSG Why We Chose It:

• Server-side rendering for SEO and performance
• App Router for modern routing patterns
• Built-in API routes for backend functionality
• Excellent developer experience
• Production-optimized builds
• Image optimization out of the box

Use Cases:

• SACE frontend (3 portals: Admin, Provider, Educator)
• Marketing websites and landing pages
• Public-facing documentation sites

Key Features We Use:

• App Router for file-based routing
• Server Components for performance
• Middleware for authentication
• API routes for lightweight backend operations

---

TypeScript

Purpose: Type-safe JavaScript Why We Chose It:

• Catch errors at compile time, not runtime
• Better IDE support and autocomplete
• Self-documenting code with types
• Easier refactoring and maintenance
• Industry standard for modern web development

Use Cases:

• All frontend codebases
• API client libraries
• Shared type definitions

---

TailwindCSS

Purpose: Utility-first CSS framework Why We Chose It:

• Rapid UI development
• Consistent design system
• No naming conventions to memorize
• Tiny production bundle sizes
• Excellent responsive design support
• Dark mode built-in

Use Cases:

• All web interfaces
• Component styling
• Responsive layouts

Configuration:

tailwind.config.js

module.exports = {
  content: ['./src/**/*.{js,ts,jsx,tsx}'],
  theme: {
    extend: {
      colors: {
        gold: '#D4AF37',
        black: '#1A1A1A',
      }
    }
  }
}

---

Zustand

Purpose: State management Why We Chose It:

• Simpler than Redux with similar power
• No boilerplate code
• TypeScript-first design
• Excellent performance
• Small bundle size (1KB)

Use Cases:

• User authentication state
• Dashboard filters and preferences
• Form state management
• Cache management

---

⚙️ Backend Stack

🐍 Python + FastAPI

🟢 Node.js + Express

📦 Pydantic

🗃️ SQLAlchemy

🔄 Alembic

Python + FastAPI

Purpose: High-performance async API framework Why We Chose It:

• Async/await support for high concurrency
• Automatic API documentation (OpenAPI/Swagger)
• Built-in data validation with Pydantic
• Excellent for ML/AI integration
• Fast (comparable to Node.js and Go)
• Type hints for better code quality

Use Cases:

• SACE backend API
• ML model serving
• Predictive analytics endpoints
• High-throughput data processing

Key Libraries:

• Pydantic: Data validation and settings management
• SQLAlchemy: Async ORM for database operations
• Alembic: Database migrations
• python-jose: JWT token handling
• passlib: Password hashing
• structlog: Structured logging

Architecture Pattern:

app/
├── api/           # API routes and endpoints
├── core/          # Configuration and database
├── models/        # SQLAlchemy ORM models
├── schemas/       # Pydantic schemas for validation
├── services/      # Business logic layer
└── main.py        # Application entry point

---

Node.js + Express

Purpose: JavaScript runtime and web framework Why We Chose It:

• JavaScript across frontend and backend
• Massive npm ecosystem
• Excellent for lightweight APIs
• Good for real-time applications (Socket.io)
• Well-understood by most developers

Use Cases:

• Lightweight microservices
• Real-time notification systems
• Webhook handlers
• Integration services

---

WhatsApp Business API

Purpose: Real-time receipt processing via WhatsApp Why We Chose It:

• Users already have WhatsApp (no app download)
• Instant delivery and processing
• Reliable messaging infrastructure
• Easy for site managers, restaurant staff, retail managers

Use Cases:

• AutoSlip receipt automation
• Real-time document submission
• Client communication

Architecture:

• Webhook integration for incoming messages
• Media download for receipt images
• Status updates sent back to users

---

🗄️ Database Stack

🐘 PostgreSQL

🔴 Redis

⚡ Async Drivers

🔄 Connection Pooling

PostgreSQL

Purpose: Primary relational database Why We Chose It:

• ACID compliance for data integrity
• Powerful query capabilities (JSON support, full-text search)
• Excellent performance at scale
• Strong data consistency guarantees
• Advanced features (CTEs, window functions, partitioning)
• Battle-tested in production environments
• Great for complex queries and analytics

Use Cases:

• SACE database (educators, providers, activities, enrollments)
• User authentication and authorization
• Transactional data
• Analytics and reporting

Configuration:

• Async Driver: psycopg[binary] version 3.x
• Connection Pooling: SQLAlchemy async engine
• Migrations: Alembic for version control

Key Tables (SACE Example):

-- Core entities
providers          -- Training providers
educators          -- Teacher records
activities         -- Training courses
enrollments        -- Educator enrollments
users              -- Authentication

-- Analytics
quality_scores     -- Provider quality metrics
risk_assessments   -- Compliance risk predictions

---

Redis

Purpose: In-memory data store for caching Why We Chose It:

• Sub-millisecond latency
• Simple key-value store
• TTL (time-to-live) for automatic cache expiration
• Pub/sub for real-time features
• Session storage
• Rate limiting

Use Cases:

• API response caching (15-minute TTL)
• Session management
• Real-time notifications
• Rate limiting for API endpoints
• Temporary data storage

Configuration:

# Redis connection
REDIS_URL = "redis://localhost:6379/0"
CACHE_EXPIRE_MINUTES = 15

---

🤖 AI & Machine Learning

TensorFlow.js

Purpose: Machine learning in JavaScript Why We Chose It:

• Run ML models in browser or Node.js
• Pre-trained models available
• Transfer learning support
• Real-time predictions without server round-trips

Use Cases:

• Client-side prediction models
• Real-time risk assessment
• Browser-based analytics

---

Python ML Stack

Purpose: Model training and data science

Libraries:

• Scikit-learn: Traditional ML algorithms
• Pandas: Data manipulation and analysis
• NumPy: Numerical computing
• Matplotlib/Seaborn: Data visualization

Use Cases:

• Compliance risk prediction (78% accuracy)
• Completion rate forecasting
• Enrollment pattern analysis
• Provider quality scoring

Model Pipeline:

1. Data extraction from PostgreSQL
2. Feature engineering with Pandas
3. Model training with Scikit-learn
4. Model evaluation and validation
5. Deployment via FastAPI endpoints
6. Continuous monitoring and retraining

---

🌐 Infrastructure & DevOps

☁️ Hetzner VPS

🌐 Nginx

⚙️ Systemd

🔒 Let's Encrypt

📚 MkDocs Material

Hetzner VPS

Purpose: Production server hosting Why We Chose It:

• Cost-effective European hosting
• Good performance for African users
• Full root access for native deployments
• Reliable uptime
• Simple pricing model

Specifications:

• IP: 46.224.40.5
• OS: Ubuntu 22.04 LTS
• Services: PostgreSQL, Redis, Nginx
• Applications: docs.isutech.co.za, sace.isutech.co.za

---

Nginx

Purpose: Web server and reverse proxy Why We Chose It:

• Industry-standard web server
• Excellent performance for static content
• Powerful reverse proxy capabilities
• SSL/TLS termination
• Load balancing support
• Minimal resource usage

Configuration Pattern:

server {
    server_name app.isutech.co.za;

    # API Backend Proxy
    location /api/ {
        proxy_pass http://localhost:8000/api/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    # Frontend Proxy
    location / {
        proxy_pass http://localhost:3000;
    }

    # SSL Configuration
    listen 443 ssl;
    ssl_certificate /etc/letsencrypt/live/app.isutech.co.za/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/app.isutech.co.za/privkey.pem;
}

---

Systemd

Purpose: Service management and auto-start Why We Chose It:

• Native Linux service management
• Automatic restart on failure
• Easy logging with journalctl
• Dependency management
• No Docker overhead

Service Pattern:

[Unit]
Description=Application Name
After=network.target postgresql.service

[Service]
Type=simple
User=root
WorkingDirectory=/var/www/app
Environment="PATH=/var/www/app/venv/bin"
ExecStart=/var/www/app/venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8000
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

---

Let’s Encrypt (Certbot)

Purpose: Free SSL certificates Why We Chose It:

• Free automated SSL certificates
• Auto-renewal built-in
• Trusted by all browsers
• Simple setup with Nginx integration

Configuration:

# Install certificate
sudo certbot --nginx -d app.isutech.co.za

# Auto-renewal (via systemd timer)
sudo systemctl status certbot.timer

---

📚 Documentation Stack

MkDocs Material

Purpose: Static site generator for documentation Why We Chose It:

• Beautiful Material Design theme
• Excellent search functionality
• Markdown-based (easy to write)
• Git-friendly workflow
• Fast static site generation
• Mobile-responsive
• Dark mode support

Use Cases:

• docs.isutech.co.za (this site)
• DocsHub SaaS product (customer-facing documentation platforms)
• Technical documentation
• Knowledge base
• Process documentation

Key Features:

• Auto-generated navigation
• Full-text search
• Code syntax highlighting
• Mermaid diagram support
• Git revision dates
• Social cards for sharing

Configuration:

mkdocs.yml

theme:
  name: material
  features:
    - navigation.instant
    - navigation.tabs
    - search.suggest
    - content.code.copy

plugins:
  - search
  - git-revision-date-localized
  - minify

---

🔐 Security Stack

JWT (JSON Web Tokens)

Purpose: Stateless authentication Why We Chose It:

• No server-side session storage needed
• Works well with distributed systems
• Contains user claims (role, permissions)
• Industry standard

Implementation:

• HS256 algorithm
• 7-day access token expiry
• 30-day refresh token expiry
• Stored in HTTP-only cookies or localStorage

---

Passlib + bcrypt

Purpose: Password hashing Why We Chose It:

• Industry-standard password hashing
• Configurable work factor (future-proof)
• Protection against rainbow tables
• Slow by design (prevents brute force)

---

CORS (Cross-Origin Resource Sharing)

Purpose: Secure cross-origin requests Configuration:

ALLOWED_HOSTS = [
    "https://sace.isutech.co.za",
    "https://docs.isutech.co.za",
    "http://localhost:3000"  # Development only
]

---

🧪 Development Tools

Version Control: Git + GitHub

Why We Chose It:

• Industry standard for version control
• Excellent branching and merging
• GitHub Actions for CI/CD
• Issue tracking and project management

---

Package Managers

• npm/pnpm: Node.js package management
• pip: Python package management
• venv: Python virtual environments

---

Code Quality Tools

• ESLint: JavaScript/TypeScript linting
• Prettier: Code formatting
• Black: Python code formatting
• mypy: Python static type checking

---

📊 Monitoring & Logging

Structured Logging (structlog)

Purpose: Machine-readable logs Implementation:

import structlog

logger = structlog.get_logger()
logger.info("user_login", user_id="123", ip="1.2.3.4")

Systemd Journald

Purpose: Centralized logging Usage:

# View logs
sudo journalctl -u sace-backend -f

# Filter by priority
sudo journalctl -u sace-backend -p err

---

🚀 Deployment Architecture

Current Architecture (SACE Example)

Internet
    ↓
Nginx (Port 443)
    ↓
    ├─→ Frontend (Next.js on port 3000)
    │   └─→ Static assets + SSR pages
    │
    └─→ Backend API (FastAPI on port 8001)
        ├─→ PostgreSQL (port 5432)
        ├─→ Redis (port 6379)
        └─→ ML Models (in-process)

Auto-Updates:
    Git Repository → Systemd Timer → Build & Deploy

---

Scalability Path

Current State: Single VPS, native deployment Next Steps:

1. Horizontal scaling with load balancer
2. Database read replicas
3. Redis cluster for distributed caching
4. CDN for static assets
5. Kubernetes for container orchestration (future)

---

💰 Cost Optimization

Why We Avoid Docker (Currently)

• Reason 1: Lower overhead on single VPS
• Reason 2: Simpler debugging and monitoring
• Reason 3: Direct access to systemd benefits
• Future: Will use Docker/K8s when scaling horizontally

Why We Use Native Deployments

• Performance: No containerization overhead
• Simplicity: Fewer moving parts
• Control: Full system access
• Cost: Maximum resource utilization

---

📈 Performance Benchmarks

API Response Times

• Health Check: < 50ms
• Database Queries: < 100ms (with caching)
• ML Predictions: < 500ms
• Full Page Load: < 2s (including SSR)

Database Performance

• Connection Pooling: 10 connections, max overflow 20
• Query Optimization: Indexed foreign keys
• Caching Strategy: 15-minute Redis TTL

---

🔄 Technology Decision Framework

When evaluating new technologies, we ask:

1. Is it production-ready? Stable version, good documentation
2. Does it solve a real problem? Not just trendy
3. Can we maintain it? Team expertise or learning curve
4. Does it scale? Handle future growth
5. What’s the cost? Licensing, hosting, maintenance
6. Is there community support? Active development, large community
7. Does it fit our stack? Integrates well with existing tools

---

📚 Technology Resources

Learning Resources

• FastAPI Documentation
• Next.js Documentation
• PostgreSQL Documentation
• TensorFlow.js Guides
• MkDocs Material

Internal Documentation

• Hetzner Server Guide
• Deployment Procedures

---

🎯 Future Technology Roadmap

Short-Term (3-6 months)

• Implement CI/CD pipelines with GitHub Actions
• Add automated testing (Jest, Pytest)
• Set up monitoring with Prometheus + Grafana
• Implement database backups automation

Medium-Term (6-12 months)

• Migrate to Docker for easier deployments
• Add Redis Cluster for high availability
• Implement CDN for static assets
• Add real-time features with Socket.io

Long-Term (12+ months)

• Kubernetes for container orchestration
• Multi-region deployments
• Advanced ML model serving (TFX, MLflow)
• Microservices architecture

---

iSu Technologies Technology Stack | Version 1.0 | Last Updated: 11/11/2025 Built for scale, optimized for Africa, powered by modern technology