Developers

How the stack fits together

Seven open-source pieces make up a Shellui stack. Use every piece, or keep the shell, your app, and Files and swap authentication and storage for Supabase.

Each piece has its own repository and lifecycle, and together they serve the Shellui frontend. The graph draws every Shellui service, then the same shell with Supabase for authentication and storage. Files and email-service stay in both views.

Map the stack

Pick a stack, then follow one box at a time. Pointing at a box or tabbing to it highlights what that box talks to, and each box title links to its section further down. Every arrow is also written out under the graph.

Stack

Seven Shellui pieces, plus the blob store and the company's mail provider. Browser pieces are static files. hosting-service on shellui.app is the all-in temporary deploy for that whole tab.

Loading architecture diagram…

Point at a box, or tab to it, to highlight what it talks to. Arrow keys pan, + and - zoom, 0 fits the view.

Connections in this view

  • Shellui shell ↔ Your app iframe + @shellui/sdk
  • Shellui shell → admin iframe at /admin
  • admin → Files iframe
  • Shellui shell → identity-service OAuth + JWT
  • Shellui shell → storage-service /storage/v1/*
  • admin → identity-service users + groups
  • Files → storage-service /storage/v1/*
  • storage-service → identity-service JWKS verify
  • storage-service → S3 or local filesystem
  • identity-service → email-service events
  • storage-service → email-service events
  • hosting-service → email-service events
  • email-service → Resend or SMTP
  • hosting-service → Browser all-in temporary deploy
  • hosting-service → identity-service JWKS verify

What Supabase replaces

The shell and your app stay the same in both views. backend.type and storage.url in shellui.config.ts decide which backend answers. Supabase does not replace email-service.

Piece Full Shellui stack Shellui + Supabase
Shell frontend @shellui/core @shellui/core
Your app Iframe with @shellui/sdk Iframe with @shellui/sdk
Sign-in identity-service, backend.type: "shellui" Supabase Auth, backend.type: "supabase"
Storage calls storage-service at /storage/v1/* Supabase Storage at /storage/v1/*
Blobs S3 or the local filesystem Held in your Supabase project
Files Files app via filesUrl, against storage-service Same Files app against Supabase Storage
Admin at /admin The admin app, set with adminUrl Registers on a Shellui identity backend only
Hosting hosting-service in your infrastructure; all-in temporary deploy of the Browser group at shellui.app Same all-in temporary deploy at shellui.app
Email email-service. Identity, storage, and hosting post events. The company uses Resend or SMTP. Same service for hosting events. Supabase Auth and Storage do not call it.

Embedded apps never call the storage API directly. They call shellui.storage, the SDK posts to the root shell, and the shell runs the request against storage.url with the signed-in user's token. That indirection is why the same app code works in both views.

shellui Frontend

The frontend lives in the shellui monorepo, a TypeScript React runtime. @shellui/core owns navigation, layout modes, themes, i18n, modals, and drawers. @shellui/sdk lets apps in iframes talk to the shell. @shellui/cli scaffolds and serves projects. Any stack can run inside the Shellui iframe.

Stack TypeScript React React Router shadcn Tailwind Workbox Roarr Sentry

shellui/shellui (opens in a new tab)

identity-service Backend

The default authentication backend is identity-service, a Django API. It covers 15 OAuth 2.0 and OpenID Connect providers, Security Assertion Markup Language (SAML) 2.0, and magic links. It issues JSON Web Token (JWT) sessions and publishes a JSON Web Key Set (JWKS).

It ships as a Docker image, and Shellui runs one at id.shellui.com. You can replace it with Supabase Auth. The shell already works with both.

The image runs its scheduler itself, so webhook retries and data retention do not need cron. It also publishes metrics in Prometheus format.

Stack Python Django django-allauth Django REST Framework Swagger ReDoc

shellui/identity-service (opens in a new tab) shellui/identity-service (opens in a new tab)

admin Frontend

The admin panel is a Vite + React app embedded in the shell at /admin. It manages users, company access, and operational data, and it reads the same identity-service as sign-in. It is static files currently deployed at admin.shellui.com.

Stack TypeScript React React Router shadcn Tailwind

shellui/admin (opens in a new tab)

storage-service Backend

The storage-service is a Django API with a Supabase-compatible Storage REST surface at /storage/v1/*. It verifies identity-service JWTs and writes blobs to S3 or the local filesystem. It ships as a Docker image and is deployed at storage.shellui.com. You can replace it with Supabase Storage.

Stack Python Django Django REST Framework django-storages Swagger ReDoc

shellui/storage-service (opens in a new tab) shellui/storage-service (opens in a new tab)

files Frontend

Files is a React file manager app. Set filesUrl and it handles browsing, upload, download, folders, permissions, and share links against storage-service or Supabase Storage. On the full stack it also embeds in the admin iframe. It is static files available at files.shellui.com.

Stack TypeScript React React Router shadcn Tailwind

shellui/files (opens in a new tab)

hosting-service All-in temporary deploy

The hosting-service is a Django API that deploys the whole Browser group as static files - the shell, your app, and Files - under one temporary URL. It ships as a Docker image in your infrastructure and is available as shellui.app. Use it in either stack while you try the product.

Stack Python Django Django REST Framework django-storages Swagger ReDoc

shellui/hosting-service (opens in a new tab) shellui/hosting-service (opens in a new tab)

email-service Backend

email-service is a Django API that sends Shellui mail. identity-service, storage-service, and hosting-service call it when EMAIL_SERVICE_API_KEY is set. An event applies that company's email rules. identity-service can also send sign-in mail directly.

The company brings its own provider, Resend or SMTP, the standard mail protocol. Mail goes out on three lanes, and each lane has its own worker. Sign-in mail uses the auth lane. Newsletters and broadcasts use the bulk lane, and other event mail uses the transactional lane.

It ships as a Docker image, and Shellui runs one at email.shellui.com. The admin app manages rules, templates, and the provider. You can run the same image yourself.

Stack Python Django Django REST Framework Celery React Email Swagger ReDoc

shellui/email-service (opens in a new tab) shellui/email-service (opens in a new tab)