Skip to main content

Shell Architecture & Overview

The Easy AppServer Shell is the main frontend platform built with Nuxt 4 that serves as the primary entry point for users.

What is the Shell?​

The Shell is a Nuxt 4-based application that serves as:

  • Platform UI - Main user interface and navigation
  • Microfrontend Host - Loads and mounts application microfrontends
  • BFF (Backend-for-Frontend) - Handles authentication flows for Kratos
  • Legacy Proxy - Integrates with existing Core5 PHP application
  • Session Manager - Manages user sessions and authentication state

Key Features​

Authentication & Authorization​

  • Ory Kratos integration for identity management
  • Ory Hydra integration for OAuth2/OIDC (planned)
  • OpenFGA integration for permissions
  • Session management and validation
  • Login/logout flows

Microfrontend Platform​

  • Module Federation support
  • Dynamic loading of application UIs
  • Shared dependency management
  • Isolated routing per application

Legacy Integration​

  • Proxy to Core5 PHP application (/c5/*)
  • Asset proxying with caching (/c5-asset/*)
  • Session sharing between new and legacy systems

Backend-for-Frontend​

  • Nuxt server routes for auth flows
  • API proxying to AppServer
  • SSR/SSG capabilities

Technology Stack​

Based on web/v2/packages/shell/README.md:

  • Framework: Nuxt 4 (with Nitro 2.12.9)
  • Runtime: Vue 3.5
  • UI Library: Easy.UI components + Tailwind CSS
  • State Management: Pinia
  • Module Federation: Vite plugin for dynamic app loading
  • Observability: OpenTelemetry (tracing, metrics, logging)
  • Database: PostgreSQL (partner database, appserver schema)

Shell Responsibilities​

1. Platform Layout​

  • Navigation menu (apps, user menu, system menu)
  • Main content area for mounted microfrontends
  • User profile menu
  • Notification system
  • Theme management (light/dark mode)

2. Application Management UI​

  • App marketplace browsing
  • Installation interface
  • App configuration screens
  • Dependency visualization
  • Permission approval flows

3. User Management​

  • Profile management
  • User preferences
  • Permission viewing
  • Session management
  • Activity history

Project Structure​

Based on the Shell repository:

web/v2/packages/shell/
├── app/
│   ├── pages/              # Nuxt pages (routes)
│   ├── components/         # Vue components
│   ├── composables/        # Vue composables
│   ├── layouts/            # Nuxt layouts
│   └── middleware/         # Route middleware
├── server/
│   ├── api/               # API routes (BFF)
│   │   ├── auth/          # Hydra login flows
│   │   ├── host/          # User session, logout
│   │   └── webhooks/      # Kratos webhooks
│   ├── middleware/        # Server middleware
│   └── utils/             # Server utilities
├── public/                # Static assets
└── nuxt.config.ts         # Nuxt configuration

State Management​

The Shell manages several types of state:

  • User Session State: Current user, roles, permissions, token
  • App Registry State: Installed apps, available apps, app metadata
  • UI State: Theme preferences, sidebar state, notifications
  • Route State: Active app, navigation history

API Communication​

The Shell communicates with multiple services:

  • AppServer GraphQL API: Queries, mutations, subscriptions for apps, settings
  • Kratos APIs: Session validation, login flows
  • Hydra APIs: OAuth2 authorization flows (planned)
  • OpenFGA API: Permission checks
  • Legacy Core5: Proxied requests for backward compatibility

Database Schema​

Shell-specific tables in appserver schema:

  • sessions - User session data
  • user_preferences - User-specific preferences and settings

BFF Routes​

Server routes for backend-for-frontend pattern:

  • POST /api/auth/hydra/login - Hydra login flow handler
  • GET /api/host/me - Current user session
  • POST /api/host/logout - Logout handler
  • POST /api/webhooks/kratos/identity - Kratos identity webhook
  • ALL /c5/* - Legacy Core5 proxy
  • GET /c5-asset/* - Legacy asset proxy with caching

Documentation​