Architecture Overview

OpenPrime follows a microservices architecture with clear separation of concerns between components.

System Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                              User Browser                                    │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                            React Frontend (3000)                             │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌────────────────────────┐ │
│  │  Context   │  │   Router   │  │   Config   │  │     UI Components      │ │
│  │  Providers │  │            │  │   Files    │  │                        │ │
│  └────────────┘  └────────────┘  └────────────┘  └────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
                    │                                        │
                    ▼                                        ▼
┌──────────────────────────────────┐       ┌──────────────────────────────────┐
│       Keycloak (8080)            │       │     Express Backend (3001)       │
│  ┌────────────────────────────┐  │       │  ┌────────────────────────────┐  │
│  │    OpenID Connect / PKCE   │  │       │  │       REST API Routes      │  │
│  │    User Management         │◀─┼───────┼─▶│       JWT Validation       │  │
│  │    Identity Federation     │  │       │  │       Business Logic       │  │
│  └────────────────────────────┘  │       │  └────────────────────────────┘  │
└──────────────────────────────────┘       └──────────────────────────────────┘
                                                            │
           ┌────────────────────────────────────────────────┼────────────────┐
           │                                                │                │
           ▼                                                ▼                ▼
┌────────────────────┐                    ┌──────────────────────┐  ┌────────────────┐
│  PostgreSQL (5432) │                    │   Injecto (8000)     │  │ StateCraft     │
│  ┌──────────────┐  │                    │   Template Processor │  │ (8001)         │
│  │    Users     │  │                    │                      │  │ TF State Mgmt  │
│  │ Environments │  │                    │  @param processing   │  │                │
│  │ Credentials  │  │                    │  @section handling   │  │ S3 + DynamoDB  │
│  └──────────────┘  │                    │  Code generation     │  │ Management     │
└────────────────────┘                    └──────────────────────┘  └────────────────┘

Component Overview

Frontend (openprime-app)

Technology: React 19, Tailwind CSS, React Router v6

Responsibilities:

• User interface rendering
• Configuration wizards
• State management via Context API
• Authentication flow (Keycloak JS)

Key Patterns:

• Configuration-driven UI generation
• Centralized context providers
• Component composition

Backend (openprime-app-backend)

Technology: Express.js, Sequelize ORM, PostgreSQL

Responsibilities:

• REST API endpoints
• JWT token validation
• Database operations
• Credential encryption
• Service orchestration

Key Patterns:

• Route/Controller/Service layers
• Middleware chain (auth, validation, logging)
• Repository pattern for data access

Authentication (Keycloak)

Technology: Keycloak 24.x

Responsibilities:

• User authentication (OIDC/PKCE)
• Session management
• Identity federation
• User provisioning

Template Processor (Injecto)

Technology: Python, FastAPI

Responsibilities:

• Template parsing (@param, @section)
• Variable substitution
• Code generation
• Validation

State Manager (StateCraft)

Technology: Python, FastAPI

Responsibilities:

• Terraform backend provisioning
• S3 bucket management
• DynamoDB table management

Data Flow

Environment Creation

1. User fills wizard form
           │
           ▼
2. Frontend validates configuration
           │
           ▼
3. POST /api/environments
           │
           ▼
4. Backend validates JWT + authorization
           │
           ▼
5. Save to PostgreSQL (JSONB)
           │
           ▼
6. Return environment ID

Code Generation

1. User requests code generation
           │
           ▼
2. Backend fetches environment config
           │
           ▼
3. Backend calls Injecto service
           │
           ▼
4. Injecto processes templates
           │
           ▼
5. Generated code returned
           │
           ▼
6. Download or push to Git

Technology Stack

Layer	Technology	Purpose
Frontend	React 19	UI framework
Styling	Tailwind CSS	Utility CSS
Routing	React Router v6	Client routing
Icons	Lucide React	Icon library
Backend	Express.js	API server
ORM	Sequelize	Database abstraction
Database	PostgreSQL 15	Data persistence
Auth	Keycloak	Identity management
Templates	Python/FastAPI	Code generation
IaC	Terraform	Infrastructure provisioning
K8s Apps	Helm	Package management

Design Principles

Configuration-Driven

UI components are generated from configuration files, not hardcoded:

// servicesConfig.js drives form generation
const schema = {
  clusterName: { type: 'string', required: true },
  version: { type: 'select', options: [...] }
};
// → Auto-generates form fields

Separation of Concerns

• Frontend: UI and user interaction
• Backend: Business logic and data
• Injecto: Template processing
• StateCraft: Infrastructure state

Security by Design

• All credentials encrypted at rest
• User isolation at database level
• JWT validation on every request
• CORS and rate limiting enabled

Scalability Considerations

Horizontal Scaling

• Frontend: Static files, CDN-friendly
• Backend: Stateless, load-balanceable
• Database: Read replicas supported

Vertical Scaling

• Injecto: CPU-bound, scales with cores
• Database: Memory for query performance

Related Documentation

• Authentication
• Data Model
• Template System