Skip to main content

Core Concepts

Understanding the fundamental concepts of Easy AppServer is essential for building applications on the platform. This guide provides a comprehensive overview of the platform architecture, application model, and key technical concepts.

Overview​

Easy AppServer is built on several key concepts that enable modular, scalable enterprise applications:

  • Applications are independent units with their own manifests, lifecycles, and permissions
  • Events drive communication between applications and platform components
  • Permissions control access using fine-grained relationship-based authorization
  • Microfrontends enable composable user interfaces
  • gRPC & GraphQL provide type-safe communication protocols

Reading Guide​

Platform Foundations​

Start here to understand the overall architecture and how applications integrate:

  1. Platform Architecture - Layering, services, and infrastructure components
  2. Application Manifest & Registration - How apps declare their structure and requirements
  3. Application Lifecycle - Registration, installation, and orchestration
  4. App State Machine & Lifecycle Enforcement - State transitions and validation

Communication Patterns​

Learn how applications communicate with each other and the platform:

  1. Event-Driven Architecture - Domain events and the event bus
  2. Hooks Architecture - Event-driven hooks with execution models
  3. Activities & Background Workflows - Request/response workflows
  4. Dependency Management - Managing app relationships

Security & Permissions​

Understand authentication, authorization, and permission enforcement:

  1. Authentication & Authorization - User and app authentication
  2. Permission Model (OpenFGA & Tuples) - Relationship-based authorization

Platform Services​

Core platform services that applications interact with:

  1. Settings Management - Schema-driven configuration
  2. Asset Serving & Microfrontends - UI integration modes
  3. gRPC Services - Platform service APIs
  4. GraphQL API & Subscriptions - Query and real-time APIs

Platform Operations​

Performance, reliability, and operational concerns:

  1. Caching Strategy - Multi-level caching across the platform
  2. Health Monitoring & Recovery - Health checks and auto-recovery

Developer Experience​

Building applications on the platform:

  1. Developer Platform & SDK - Node.js SDK and tooling

Key Principles​

Modularity​

Applications are independent units that can be developed, deployed, and versioned separately. Each app is responsible for its own:

  • Backend services via Docker containers with orchestration
  • Frontend components as microfrontends (Module Federation, Web Components, ESM)
  • Data storage with isolation and encryption
  • Business logic encapsulated within app boundaries

Composability​

Applications can depend on and interact with other applications:

  • Declare HARD or SOFT dependencies with semantic versioning
  • Subscribe to hooks from other apps for event-driven integration
  • Execute activities in other apps for request/response workflows
  • Call APIs via the intelligent HTTP proxy with permission checks
  • Extend UI by contributing navigation items and components

Security First​

Every interaction is authenticated and authorized:

  • Users authenticate via Ory Kratos with session management
  • Applications authenticate via X.509 certificates with signature verification
  • All requests are signed and timestamped to prevent replay attacks
  • OpenFGA provides fine-grained relationship-based permissions
  • Encryption protects sensitive settings (AES-256-GCM)

Event-Driven​

Applications communicate through events rather than direct coupling:

  • Publish domain events when state changes (app.installed, settings.updated)
  • Subscribe to events via RabbitMQ or in-memory bus
  • Implement eventual consistency patterns across distributed components
  • Cache invalidation through event propagation
  • GraphQL subscriptions bridge events to real-time UIs

Type-Safe Communication​

Strong typing throughout the stack:

  • Protocol Buffers for gRPC service definitions
  • GraphQL schema with code generation
  • TypeScript SDK with full type inference
  • Manifest validation at registration time
  • Settings schemas enforce runtime types

Suggested Reading Paths​

For Application Developers​

Building your first app? Follow this path:

  1. Application Manifest - Define your app
  2. Developer Platform & SDK - Set up development environment
  3. Application Lifecycle - Understand installation flow
  4. Settings Management - Add configuration
  5. Hooks Architecture - Integrate with other apps
  6. Asset Serving & Microfrontends - Build UI

For Platform Operators​

Operating and monitoring the platform? Follow this path:

  1. Platform Architecture - Understand overall structure
  2. Authentication & Authorization - Security model
  3. Permission Model - Authorization details
  4. Health Monitoring & Recovery - Operational health
  5. Caching Strategy - Performance optimization
  6. Event-Driven Architecture - Event bus operation

For Technical Architects​

Designing application architectures? Follow this path:

  1. Platform Architecture - System design
  2. Dependency Management - App relationships
  3. Event-Driven Architecture - Communication patterns
  4. Hooks Architecture - Event-driven integration
  5. Activities & Background Workflows - Request/response patterns
  6. App State Machine - State management

Key Resources​

Application Model​

Applications in Easy AppServer consist of:

  • Manifest: Declarative descriptor with assets, permissions, dependencies, settings
  • Certificate: X.509 certificate for identity and request signing
  • Assets: Frontend files (JS, CSS) served with SRI integrity checks
  • Docker Containers: Backend services orchestrated by the platform
  • Permissions: OpenFGA tuples defining what the app can access
  • Settings: Schema-driven configuration with validation and encryption
  • Dependencies: Relationships to other required applications

Permission Model​

Fine-grained access control using relationship tuples:

  • Routes: (role:advertiser#assignee, accessible_by, route:/api/campaigns)
  • Hooks: (app:backend, trigger, hook:user.created)
  • Activities: (app:worker, execute, activity:generate-report)
  • Settings: (role:admin#assignee, write, setting:api-key)

Communication Patterns​

Three primary patterns for app-to-app communication:

  • Event Bus: Fire-and-forget async events (app.installed, settings.updated)
  • Hooks: Event-driven with synchronous responses (user.created, order.placed)
  • Activities: Request/response with routing strategies (generate-report, send-email)

Next Steps​

Choose your path and dive into the concepts that matter most for your role. Each concept page includes code references, diagrams, and links to related guides.

Start with Platform Architecture for a high-level overview, or jump directly to Developer Platform & SDK to start building.