Skip to main content

Helix Platform Documentation

Welcome to the Helix Platform developer documentation. This documentation covers everything you need to know about building, deploying, and maintaining the Helix microservices platform.

📚 Documentation Structure​

🚀 Getting Started​

Start here if you're new to the Helix platform.

🏗️ Architecture​

Understand the platform's technical architecture.

💻 Development​

Tools, workflows, and guidelines for development.

🚢 Deployment​

Production deployment and infrastructure management.

🔧 Microservices​

Documentation for each microservice in the platform.

Core Services​

AI Services​

Supporting Services​

📦 Shared Libraries​

Reusable code that ALL services use - Don't duplicate generic functionality!

Understanding Shared Libraries​

Shared libraries contain generic, reusable code used across all microservices. Before writing ANY generic code, check if it exists here or should be added here.

When to Use Shared Libraries​

✅ USE existing shared libraries when:

  • You need authentication guards, validators, or middleware
  • You need common types, interfaces, or constants
  • You need utility functions (retry logic, crypto, date formatting)
  • You're implementing pagination, error handling, or logging
  • You need database connection management

When to ADD to Shared Libraries​

✅ ADD NEW CODE to shared libraries when:

  • The functionality is generic and could be used by multiple services
  • It's a NestJS component (guard, pipe, decorator, filter, middleware)
  • It's a utility function with zero service-specific logic
  • It's a common type, interface, or constant used across services
  • You find yourself copying code between services

❌ DON'T add to shared libraries when:

  • Code is service-specific or domain-specific
  • Code depends on service-specific models or business logic
  • It's a one-off implementation
  • It tightly couples services together

Available Library Categories​

  • Constants (@helix/shared/constants) - Error codes, defaults, rate limits
  • Decorators (@helix/shared/decorators) - @CurrentUser(), @TenantId() parameter decorators
  • Guards (@helix/shared/guards) - JWT auth, roles, scopes, tenant access
  • Filters (@helix/shared/filters) - Exception handling (HTTP, Prisma)
  • Middleware (@helix/shared/middleware) - Auth, logging, tenant context, rate limiting
  • Pipes (@helix/shared/pipes) - Pagination, UUID validation, data transformation
  • Validators (@helix/shared/validators) - Zod schemas for validation
  • Utils (@helix/shared/utils) - Retry logic, crypto, circuit breakers, date formatting
  • Types (@helix/shared/types) - Shared TypeScript types
  • Interfaces (@helix/shared/interfaces) - Cross-service interfaces

Creating a New Shared Library​

When you need a new category of shared code:

# Generate a new shared library
nx generate @nx/node:library <library-name> --directory=libs/shared/<library-name>

# Example: Creating a new "transformers" library
nx generate @nx/node:library transformers --directory=libs/shared/transformers

After creating:

  1. Add exports to libs/shared/<library-name>/src/index.ts
  2. Update tsconfig.base.json paths if needed (Nx usually handles this)
  3. Import using @helix/shared/<library-name> in services
  4. Document the library's purpose in a README.md

Golden Rule: If it's generic and reusable, it belongs in /libs/shared/. Use existing libraries first, extend them second, create new ones only when necessary.

🎯 Quick Links​

For New Developers​

  1. Read the Introduction
  2. Set up local environment with Docker Setup
  3. Learn available Make Commands
  4. Review Development Guidelines
  5. Explore the API Gateway as the entry point

For DevOps​

  1. Review Deployment Guide
  2. Understand Terraform Overview
  3. Check infrastructure costs in Deployment Guide

For Backend Developers​

  1. Understand Build Architecture
  2. FIRST: Check Shared Libraries before writing generic code
  3. Follow Development Guidelines
  4. Learn how to Add New Services
  5. Use Database & Prisma for data access

For Integrations​

  1. Read Adding API Integrations
  2. Understand secret management in Deployment Guide
  3. Follow security patterns in Development Guidelines

🏗️ Platform Architecture​

┌─────────────────────── Helix Platform ───────────────────────┐
│                                                              │
│  ┌────────────────── API Gateway ──────────────────┐         │
│  │  - Request routing                              │         │
│  │  - Rate limiting                                │         │
│  │  - Request ID tracking                          │         │
│  └──────────────---──┬─────────────────────────────┘         │
│                      │                                       │
│  ┌──────────-────────┼─── Microservices ───────────┐         │
│  │                   │                             │         │
│  │  ┌────────────-───▼────┐  ┌────────────────┐    │         │
│  │  │  Auth Service       │  │ Tenant Service │    │         │
│  │  └─────────────────────┘  └────────────────┘    │         │
│  │                                                 │         │
│  │  ┌────────────────┐  ┌────────────────┐         │         │
│  │  │  KIRA (AI)     │  │  VERA (Search) │         │         │
│  │  └────────────────┘  └────────────────┘         │         │
│  │                                                 │         │
│  │  ┌────────────────┐  ┌────────────────┐         │         │
│  │  │  File Service  │  │  Admin Service │         │         │
│  │  └────────────────┘  └────────────────┘         │         │
│  └──────────────────────────────────────────────---┘         │
│                                                              │
│  ┌─────────────── Data Layer ───────────-───┐                │
│  │  - PostgreSQL (3-tier architecture)      │                │
│  │  - Redis (caching & pub/sub)             │                │
│  │  - S3 (file storage)                     │                │
│  └──────────────────────────────────────────┘                │
└─────────────────────────────────────────────────--───────────┘

📊 Technology Stack​

Backend​

  • Runtime: Node.js 20+
  • Framework: NestJS
  • Language: TypeScript (strict mode)
  • Database: PostgreSQL 15
  • Cache: Redis 7
  • ORM: Prisma

Infrastructure​

  • Container: Docker + Docker Compose
  • Orchestration: ECS Fargate
  • IaC: Terraform
  • CI/CD: GitHub Actions
  • Monitoring: CloudWatch
  • Secrets: AWS Secrets Manager

Development​

  • Monorepo: Nx
  • Testing: Jest
  • Linting: ESLint
  • Formatting: Prettier

🎓 Learning Paths​

Path 1: Frontend Developer​

Goal: Integrate with Helix APIs

  1. Start: API Gateway - Understand API structure
  2. Read: Auth Service - Learn authentication
  3. Review: Development Guidelines - Security patterns

Path 2: Backend Developer​

Goal: Build new services and features

  1. Start: Development Guidelines - Core principles
  2. Learn: Build Architecture - Nx monorepo
  3. Practice: Adding New Service - Create service
  4. Reference: Shared Libraries - ALWAYS check before writing generic code
  5. Study: Database & Prisma - Data access

Path 3: DevOps Engineer​

Goal: Deploy and maintain infrastructure

  1. Start: Terraform Overview - Infrastructure basics
  2. Deep Dive: Deployment Guide - Complete deployment
  3. Learn: Docker Setup - Container architecture
  4. Practice: Deploy to staging using GitHub Actions

Path 4: Platform Architect​

Goal: Understand and evolve the platform

  1. Read: Build Architecture - System design
  2. Study: Database & Prisma - Data architecture
  3. Review: All Services - Service boundaries
  4. Understand: Shared Libraries - Code organization
  5. Plan: Adding New Service - Extensibility

🤝 Contributing​

When contributing to the platform:

  1. Follow existing patterns - Check similar services for reference
  2. Use shared libraries - Don't duplicate generic functionality
  3. Write tests - Aim for >80% coverage
  4. Document changes - Update relevant docs
  5. Follow TypeScript strict mode - No any types
  6. Review Development Guidelines - Essential do's and don'ts

📋 Common Tasks​

I want to...​

...start developing locally → See Make Commands Reference

...add a new API integration → See Adding API Integrations

...create a new microservice → See Adding New Service

...understand the database structure → See Database & Prisma

...deploy to staging → See Deployment Guide

...use shared code (guards, pipes, etc.) → See Shared Libraries section above

...run tests → Run make test or see Make Commands

...troubleshoot Docker issues → See Docker Setup and Make Commands

📞 Support​

Platform Version: v1.0.0-rc

Documentation Status: ✅ Production-Ready

Last Updated: 2025-01-23