Skip to main content

Platform Architecture

Comprehensive overview of Easy AppServer's layered architecture following clean architecture and domain-driven design principles.

Architectural Layers​

Based on pkg/v2/README.md, the AppServer follows a clean architecture pattern:

┌─────────────────────────────────────────────────────────┐
│                  Presentation Layer                      │
│   (HTTP, gRPC, GraphQL, WebSocket Servers)              │
│   pkg/v2/presentation/*                                  │
└─────────────────────────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────────┐
│                  Application Layer                       │
│   (Business Logic Services & Use Cases)                 │
│   pkg/v2/application/*                                   │
└─────────────────────────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────────┐
│                    Domain Layer                          │
│   (Core Business Rules & Entities)                      │
│   pkg/v2/domain/*                                        │
└─────────────────────────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────────┐
│                Infrastructure Layer                      │
│   (Technical Implementations)                           │
│   pkg/v2/infrastructure/*                                │
└─────────────────────────────────────────────────────────┘

Presentation Layer (pkg/v2/presentation/)​

Handles external communication protocols:

  • HTTP Server: REST API, asset serving, proxy (presentation/http/)
  • gRPC Server: High-performance RPC for app communication (presentation/grpc/)
  • GraphQL Server: Real-time queries, mutations, subscriptions (presentation/graphql/)
  • WebSocket Server: Live data streaming (presentation/websocket/)
  • UI Server: Microfrontend asset serving (presentation/ui/)

Application Layer (pkg/v2/application/)​

Implements business logic and use cases:

  • Marketplace: App installation, registration, lifecycle (application/marketplace/)
  • Hooks: Lifecycle hook management (application/hooks/)
  • Activity: Activity tracking and execution (application/activity/)
  • Settings: Encrypted settings management (application/settings/)
  • Proxy: HTTP proxy with permission checks (application/proxy/)
  • UI Engine: Microfrontend serving (application/ui/)
  • Orchestration: Docker container management (application/orchestration/)

Domain Layer (pkg/v2/domain/)​

Contains core business entities and rules:

  • App: Application entities and value objects (domain/app/)
  • Lifecycle: State machines and transitions (domain/lifecycle/)
  • Dependency: Dependency graph management (domain/dependency/)
  • Route: HTTP route specifications (domain/route/)
  • Permission: Permission models (domain/permission/)
  • Settings: Settings domain models (domain/settings/)
  • Event: Domain events (domain/event/)
  • Hook: Hook specifications (domain/hook/)
  • Activity: Activity models (domain/activity/)

Infrastructure Layer (pkg/v2/infrastructure/)​

Provides technical implementations:

  • Auth: User and app authentication (infrastructure/auth/, infrastructure/authz/)
  • Storage: PostgreSQL repositories (infrastructure/storage/postgres/)
  • Event Bus: RabbitMQ pub/sub (infrastructure/eventbus/)
  • Event Store: Event sourcing infrastructure (infrastructure/eventstore/) - Interface defined but not wired into runtime
  • Permission Cache: Distributed permission caching (infrastructure/permission/cache/)
  • Rate Limiting: Redis-based rate limiting (infrastructure/ratelimit/)
  • Circuit Breaker: Failure protection (infrastructure/circuitbreaker/)
  • Stream: gRPC streaming (infrastructure/stream/)
  • Docker: Container management (infrastructure/docker/)
  • Encryption: AES-256-GCM encryption (infrastructure/encryption/)
  • Health: Health checking (infrastructure/health/)
  • Middleware: HTTP/gRPC middleware (infrastructure/middleware/)
Implementation Status

The event store infrastructure exists at pkg/v2/infrastructure/eventstore/ but is not currently wired into the event bus runtime (pkg/v2/server/eventbus.go). The platform uses RabbitMQ for event distribution without persistent event sourcing.

Core Components​

AppServer Core (Go Backend)​

The main server binary (cmd/appserver-v2/) that orchestrates:

  • Server Coordinator (pkg/v2/server/) - Manages all server lifecycles
  • Configuration (pkg/v2/config/) - Environment-based configuration
  • Telemetry (pkg/v2/telemetry/) - Logging, metrics, tracing interfaces

Orchestrator (Optional Plugin)​

Standalone binary (cmd/orchestrator/) that:

  • Listens to install/uninstall events
  • Deploys Docker containers automatically
  • Manages container lifecycle
  • Can run independently of core AppServer

Shell (Nuxt 4 Frontend)​

Browser application (web/v2/packages/shell/) serving as:

  • Platform UI: Main user interface
  • Microfrontend Host: Module Federation loader
  • BFF: Nuxt server routes for auth flows
  • Legacy Proxy: Core5 PHP integration

SDKs​

Node.js SDK (web/v2/packages/appserver-sdk/)​

Backend SDK for app development:

  • Lifecycle hooks implementation
  • Manifest building
  • Database integration
  • Certificate management

Frontend SDK (web/v2/packages/appserver-frontend-sdk/)​

Browser SDK for microfrontends:

  • Session context access
  • Settings management
  • Authenticated fetch
  • Module Federation adapter

TypeScript Client (web/v2/packages/client-ts/)​

Low-level client library:

  • GraphQL client
  • HTTP client
  • Type-safe API calls

Auth Client (web/v2/packages/auth-client/)​

Authentication utilities

Telemetry (web/v2/packages/telemetry/)​

Observability helpers

Federation Utils (web/v2/packages/federation-utils/)​

Module Federation utilities

Infrastructure Services​

PostgreSQL​

Primary data store:

  • Application metadata
  • User data
  • Settings (encrypted)
  • Activity logs
  • Event history

Redis​

Distributed caching:

  • Permission cache
  • Settings cache
  • Rate limiting counters
  • Session data

RabbitMQ​

Event bus for:

  • Domain event pub/sub
  • Cross-instance state synchronization
  • Cache invalidation
  • Lifecycle events

Ory Stack​

Kratos​

User identity management:

  • Registration and login
  • Session management
  • Account recovery

Hydra (Planned)​

OAuth2/OIDC provider (not yet integrated)

Oathkeeper​

Reverse proxy and access control

OpenFGA​

Fine-grained authorization:

  • Relation-based access control
  • Permission checking
  • Role management

Telemetry Stack​

Implementation Status

Telemetry interfaces are defined in pkg/v2/telemetry/, but concrete exporters for external systems are not yet implemented. The current telemetry layer provides interfaces for logging, metrics, and tracing without actual collection/export.

Planned integrations:

  • Prometheus: Metrics collection
  • Loki: Log aggregation
  • Tempo: Distributed tracing
  • Grafana: Visualization

Data Flow Patterns​

User Authentication Flow​

  1. User accesses Shell
  2. Shell checks for Kratos session cookie
  3. If not authenticated, redirects to Kratos login
  4. Kratos authenticates and creates session
  5. Shell validates session with AppServer
  6. AppServer checks OpenFGA permissions
  7. User accesses platform

Application Installation Flow​

  1. User requests app installation via GraphQL
  2. AppServer resolves dependencies (topological sort)
  3. AppServer validates dependency existence, cycles, and installed state
  4. AppServer allocates resources (routes, permissions)
  5. Orchestrator (if enabled) starts Docker containers
  6. AppServer calls app onInstall lifecycle hook
  7. App registers microfrontends and routes
  8. App publishes app.installed event
  9. App is ready to use
Dependency Validation

Version constraints declared in manifests are stored but not currently enforced by the dependency resolver (pkg/v2/domain/service/dependency_resolver.go). The resolver checks for dependency existence, cycles, and installed state only. Semantic version range validation is planned for future implementation.

Microfrontend Loading Flow​

  1. Shell loads app manifest from AppServer
  2. Shell fetches remote entry with SRI verification
  3. Shell initializes Frontend SDK with session context
  4. Shell mounts component into router
  5. Component uses SDK for authenticated API calls

Event Publishing Flow​

  1. App publishes domain event via event bus
  2. RabbitMQ routes to subscribed applications
  3. AppServer instances receive event
  4. Subscribers process event
  5. Cache invalidation triggered across all instances

Communication Patterns​

User → Shell → AppServer​

  • GraphQL queries/mutations/subscriptions
  • HTTP REST for assets
  • WebSocket for real-time updates

App → AppServer​

  • gRPC with mTLS
  • Certificate-based authentication
  • Request signature verification
  • Replay protection

App → App​

  • Via AppServer HTTP proxy
  • Permission verification before forwarding
  • Rate limiting enforcement
  • Circuit breaking protection

AppServer → Infrastructure​

  • PostgreSQL for persistence
  • Redis for caching
  • RabbitMQ for eventing
  • OpenFGA for permissions

Security Architecture​

Transport Security​

  • TLS/mTLS for all gRPC communication
  • HTTPS for all HTTP communication
  • Certificate-based app authentication

Authentication​

  • User Auth: Kratos sessions with cookies
  • App Auth: X.509 certificates with request signing
  • Signature Verification: Timestamp validation with replay protection

Authorization​

  • OpenFGA relation-based access control
  • Permission checks before proxy forwarding
  • Distributed permission caching
  • Event-driven cache invalidation

Data Protection​

  • AES-256-GCM encryption for settings
  • TLS for data in transit
  • Secure credential storage

Scalability & High Availability​

Horizontal Scaling​

  • Multiple AppServer instances run concurrently
  • RabbitMQ event bus synchronizes state across instances
  • State changes propagated via events
  • Stateless design allows dynamic scaling

Database Scaling​

  • PostgreSQL replication (primary + replicas)
  • Connection pooling
  • Query optimization

Cache Scaling​

  • Redis clustering
  • Distributed cache invalidation via events
  • Consistent hashing

Message Queue Scaling​

  • RabbitMQ clustering
  • Queue federation
  • Message persistence

Load Balancing​

  • Distribute requests across AppServer instances
  • Health check-based routing
  • Session affinity (if needed)

Next Steps​