App Studio

App Studio is a reusable full-stack SaaS admin starter for building and operating custom products.

By default, the admin app is intended to run under a mounted path such as /admin, while the root / can be served by a separate CMS or public website.

The intended use is:

• start with a real repo, not just a UI kit
• keep a reusable core for auth, users, orgs, billing, settings, and admin
• add your own product-specific models, pages, and workflows on top
• ship with your own containers, pipelines, and deployment flow
• bootstrap new products with app.sh, install the NPM UI/API packages, then generate app code from an editable schema

This is the right shape for products such as:

• an admin portal
• a site provisioning portal
• a multi-tenant control plane
• a customer success or operations dashboard
• a product that sells plans and manages installations

What App Studio Is

App Studio is a repo-level starter for:

• app: React/Next admin UI
• api: backend service
• devops: Docker and pipeline setup
• billing: Stripe-ready product model pattern
• core domains: users, orgs, projects, providers, settings, admin

App Studio now supports a hybrid bootstrap model: this repo remains the source foundation, while reusable API/UI pieces can be published as NPM packages and installed into product repos.

Bootstrap With app.sh

For new projects, start with a blank repo and download app.sh into the repo root.

curl -fsSL "$APPSTUDIO_BOOTSTRAP_URL" -o app.sh
chmod +x app.sh
./app.sh init --name my-product
./app.sh edit-schema
./app.sh install
./app.sh generate

The release pipeline publishes the latest script to the application-studio S3 bucket by default:

curl -fsSL "https://s3.amazonaws.com/application-studio/app.sh" -o app.sh

The S3 release upload is configured with:

APPSTUDIO_BOOTSTRAP_S3_URI=s3://application-studio/app.sh

The bucket or CloudFront distribution should allow public read access to that object. If the bucket still uses object ACLs, set APPSTUDIO_BOOTSTRAP_S3_ACL=public-read; otherwise leave it unset and use a bucket policy. The pipeline also uploads a versioned copy next to it, such as app-0.1.0.sh, unless APPSTUDIO_BOOTSTRAP_S3_VERSION_URI is set.

If you already have app.sh, the local commands are:

./app.sh init --name my-product
./app.sh edit-schema
./app.sh install
./app.sh generate

The intended flow is:

1. init creates a lightweight local skeleton and appstudio.schema.json.
2. You edit the schema for the product shape.
3. install installs the reusable UI and API packages from NPM, or links local checkouts when configured.
4. generate links local packages when available, then overlays local routes, models, pages, and module code on top.

The generated repo also gets its own deployable-app scaffold:

• bitbucket-pipelines.yml for Docker image publish and CloudFormation deploy
• docker-compose.yml for local app/API development
• devops/docker/Dockerfile.app
• devops/docker/Dockerfile.api
• devops/cloudformation/app.yml

The default packages are @spacemade/ui and @spacemade/api:

./app.sh install

When developing the reusable packages and a product app side by side, point the app at the local checkout so imports resolve through node_modules exactly like the published packages:

SPACEMADE_UI_PATH=../appstudio \
SPACEMADE_API_PATH=../appstudio/api \
./app.sh install
./app.sh generate

./app.sh link-core ../appstudio also works directly. With no path, it checks common sibling folders such as ../appstudio, ../spacemade-ui, and ../ui.

That creates:

node_modules/@spacemade/ui  -> ../appstudio
node_modules/@spacemade/api -> ../appstudio/api

This is the best local loop because the product app exercises the real package names and package boundaries while still picking up edits from the reusable package checkout immediately.

Repo And NPM Package

Use the repo when you need:

• frontend app structure
• backend API structure
• data model conventions
• Docker and deployment setup
• pipelines
• environment contracts
• product bootstrapping

Use NPM packages for:

• reusable API/UI core
• shared UI components
• shared types and schemas
• Stripe and auth helpers
• the schema-driven generator

Recommended strategy:

1. Keep appstudio as the source repo for the reusable UI, API, and generator.
2. Publish stable pieces as @spacemade/* packages.
3. Build product repos from a blank skeleton using app.sh.
4. Let the generator add product-specific modules on top of the installed packages.

For example:

appstudio/                # starter repo
admin-app/             # product repo built from appstudio

@spacemade/ui          # reusable admin UI and generator CLI
@spacemade/api         # reusable API service
@spacemade/types       # shared types
@spacemade/stripe      # Stripe helpers
@spacemade/auth        # auth helpers

Best Fit Product Example

If you are building an Admin portal, appstudio should power:

• account creation and login
• organization and workspace management
• user invites and roles
• pricing and subscriptions
• product instance creation
• install management
• environment and provider configuration
• support/admin operations

Then your product repo adds:

• product-specific models
• site/install lifecycle flows
• domain mapping
• provisioning actions
• template selection
• product management UI

Current Structure

api/
  lib/
    controllers/
    data/
    models/
    repositories/
    services/
  pages/api/
devops/
  docker/
src/
  app/
  components/
  config/
  data/
  lib/
  types/
docs/
  cms-quickstart.md
  gallery-quickstart.md
  gpu-marketplace-quickstart.md
  metaverse-quickstart.md
  migration-plan.md
  modules.md
  nft-quickstart.md
  simple-cms-quickstart.md
docker-compose.yml
bitbucket-pipelines.yml
cmd.sh

Mounted Admin App

App Studio is designed to work as an admin application mounted under a subpath.

Examples:

• /admin
• /custom

Recommended deployment shape:

• / serves the public CMS or website
• /admin proxies to the App Studio React app
• /admin/api or a sibling API hostname proxies to the App Studio API service

Main setting:

• NEXT_PUBLIC_APP_BASE_PATH=/admin

This is wired through:

• next.config.ts
• src/config/app.ts
• src/lib/app-paths.ts
• middleware.ts

Core Architecture

App Studio should own the reusable SaaS backbone.

Core domains:

• auth
• users
• orgs
• projects
• providers
• pricing
• settings
• admin

Product-specific domains should be added by the product repo.

Examples:

• admin-install
• admin-template
• managed-site
• managed-domain
• managed-module
• managed-theme
• deployment-job

How To Build A Custom Product On Top

1. Start With App Studio Core

Keep these areas generic:

• login and session model
• org and membership model
• user roles and admin permissions
• plans and billing entities
• provider registry
• settings pages
• admin shell

2. Add Your Product Domain

For a notepad app, add models such as:

• Notebook
• Note
• NoteTag
• SharedNotePermission

For an Admin portal, add models such as:

• AdminInstall
• AdminTemplate
• AdminDomain
• ProvisionJob
• ManagedEnvironment
• BackupJob

3. Add Product Routes

Examples:

• /installs
• /installs/[id]
• /templates
• /domains
• /deployments

4. Add Product API

Examples:

• api/pages/api/installs/index.ts
• api/pages/api/installs/[id].ts
• api/pages/api/templates/index.ts
• api/pages/api/provision/index.ts

5. Add Product Services

Examples:

• install provisioning service
• domain connection service
• deployment orchestration service
• backup and restore service

Backend Pattern

The API follows this structure:

• models: domain shapes
• repositories: data access
• services: business logic
• controllers: response assembly
• pages/api: HTTP handlers

Example flow:

HTTP route
  -> controller
  -> service
  -> repository
  -> model/data

Current reusable examples live in:

• api/lib/models
• api/lib/services
• api/lib/controllers
• api/pages/api

Base App Startup

The reusable admin base now includes starter coverage for:

• activity
• addresses
• forms
• invoices
• media
• orgs
• posts
• products
• projects
• providers
• purchases
• sites
• subscriptions
• tags
• tickets
• usage
• users

For database startup in the API service:

1. Configure database env vars for api
2. Run npm run migrate:up
3. Run npm run seed:up

Reference files:

• api/migrations/20260326093000-baseline.js
• api/seeders/20260326094500-base-app.js
• api/doc/migration-baseline.md

Local Docker Dev

App Studio is set up for local containerized development with bind mounts and watch-friendly polling.

Main files:

• docker-compose.yml
• devops/docker/Dockerfile.app
• devops/docker/Dockerfile.api
• devops/docker/entrypoint/app-docker-entrypoint.sh
• devops/docker/entrypoint/api-docker-entrypoint.sh
• .env

Recommended local flow:

1. Configure .env
2. Start containers with docker compose up --build
3. Open the app on http://localhost:3000
4. Open the API on http://localhost:3001
5. Run npm run migrate:up and npm run seed:up inside the API container when ready

Dev-friendly behavior included:

• bind mounts for app and API source
• polling enabled for WSL/docker watch behavior
• named volumes for node_modules and .next cache
• API bind mounts for config, migrations, seeders, and lib
• default local auth/session env values for quick access

Important local envs:

• NEXT_PUBLIC_APP_BASE_PATH
• WATCHPACK_POLLING_INTERVAL
• API_WATCHPACK_POLLING_INTERVAL
• NEXT_PUBLIC_DEFAULT_USER_ID
• NEXT_PUBLIC_DEFAULT_ROLE
• NEXT_PUBLIC_DEFAULT_ORG_ROLE
• DEFAULT_USER_ID
• DEFAULT_ROLE
• DEFAULT_ORG_ROLE

Security Layer

App Studio now includes a reusable starter security layer for the admin surface.

Frontend security files:

• middleware.ts
• src/helpers/permissions/index.ts
• src/lib/auth.ts
• src/lib/security.ts

API security files:

• api/lib/auth/session.ts
• api/lib/security/permissions.ts
• api/lib/middleware/with-auth.ts

Default behavior:

• / and /pricing remain public
• core app routes require an authenticated session
• admin requires admin-style access
• API domain routes require auth and check CRUD permission by role

Agents

App Studio now includes starter agent scaffolding, but agents are treated as part of the product being built, not tied to a fixed legacy app.

Files:

• src/app/agents/page.tsx
• api/lib/models/agent.ts
• api/lib/data/agents.ts
• api/pages/api/agents/index.ts

Use agents for the current product:

• support agents for the admin portal
• publishing agents for the CMS website
• provisioning agents for install systems
• product-specific automation workers

Starter session inputs:

• frontend cookies: appstudio_user_id, appstudio_role, appstudio_org_role, appstudio_active_org_id, appstudio_active_project_id
• API headers: x-appstudio-user-id, x-appstudio-role, x-appstudio-org-role, x-appstudio-org-id, x-appstudio-project-id
• env fallbacks for local setup: NEXT_PUBLIC_DEFAULT_USER_ID, NEXT_PUBLIC_DEFAULT_ROLE, NEXT_PUBLIC_DEFAULT_ORG_ROLE, DEFAULT_USER_ID, DEFAULT_ROLE, DEFAULT_ORG_ROLE

Frontend Pattern

The frontend should stay focused on:

• dashboards
• settings
• admin workflows
• product configuration
• entity listing/detail pages

The reusable shell lives in:

• src/app/layout.tsx
• src/components
• src/config

Stripe Setup

Use Stripe as part of the reusable core, not as product-only code.

Stripe belongs in the platform layer because most admin products need:

• products
• plans
• subscriptions
• invoices
• payment method handling
• entitlement checks

Recommended Stripe Model

Create platform entities like:

• BillingProduct
• BillingPlan
• Subscription
• Invoice
• UsageEvent

Then map product-specific entitlements on top:

• install_limit
• template_limit
• custom_domain_limit
• backup_retention_days

Suggested Stripe Flow

1. User signs up.
2. User creates or joins an org.
3. User selects a plan.
4. Stripe checkout creates a subscription.
5. Webhook updates local subscription state.
6. Entitlements unlock product actions.

Stripe Setup In App Studio

Add these areas next:

• api/lib/models/billing-*
• api/lib/services/stripe-service.ts
• api/lib/controllers/stripe-controller.ts
• api/pages/api/webhook/stripe.ts
• src/app/pricing
• src/app/settings/billing

Example Environment Variables

STRIPE_SECRET_KEY=sk_test_xxx
STRIPE_PUBLISHABLE_KEY=pk_test_xxx
STRIPE_WEBHOOK_SECRET=whsec_xxx

Handling Users

User handling belongs in core.

Recommended platform user model:

• User
• UserPassword or auth provider identity
• Org
• OrgMembership
• UserRole
• Invite

Recommended roles:

• owner
• admin
• editor
• viewer

For an Admin portal, users should be scoped through org/workspace membership, not just global access.

That gives you:

• multi-tenant separation
• team billing ownership
• shared installations inside an org
• support/admin escalation paths

Admin Portal Design

If the goal is “buy and launch and manage product installs”, your product repo should likely include these domains:

Platform Core

• users
• orgs
• billing
• admin
• providers
• settings

Product Layer

• install catalog
• provisioning jobs
• deployment environments
• connected domains
• backups
• templates
• themes
• plugins/modules

Key Workflows

1. Customer signs up.
2. Customer picks a plan.
3. Customer creates an org/workspace.
4. Customer launches an install.
5. System provisions the install.
6. Customer manages domains, templates, and billing.
7. Admin/support can inspect and intervene when needed.

Containers

App Studio includes starter container files:

• docker-compose.yml
• devops/docker/Dockerfile.app
• devops/docker/Dockerfile.api

Current local services:

• app
• api
• mysql

Start from:

• .env

Commands

App Studio includes a repo command wrapper modeled after the parent project:

• cmd.sh

Examples:

./cmd.sh init cms
./cmd.sh init cms --force
./cmd.sh init simple-cms
./cmd.sh init gallery
./cmd.sh init nft
./cmd.sh init gpu
./cmd.sh init metaverse
./cmd.sh init all --force

Pipelines

Bitbucket pipeline file:

• bitbucket-pipelines.yml

Current pipeline shape:

• PR/package verification with npm pack --dry-run
• tag-based publish for @spacemade/ui
• tag-based publish for @spacemade/api
• tag-based upload of app.sh to s3://application-studio/app.sh

Generated product apps should own their Docker images, CloudFormation templates, and runtime deployment pipeline.

Environment Contract

Example frontend/platform config:

NEXT_PUBLIC_APP_NAME=App Studio
NEXT_PUBLIC_ENABLED_MODULES=projects,orgs,providers,users,pricing,settings,admin

Example richer product:

NEXT_PUBLIC_APP_NAME=Admin
NEXT_PUBLIC_ENABLED_MODULES=projects,orgs,providers,users,pricing,settings,admin

For an Admin product, avoid turning on AI-style modules unless you actually build them.

Recommended Next Steps

1. Add auth and session handling.
2. Add org membership and invite models.
3. Add Stripe models and webhook handling.
4. Add install models.
5. Add provisioning job service.
6. Add deployment/provider adapters.
7. Add admin pages for install lifecycle management.

Practical Recommendation

Use this repo as the source for the reusable @spacemade/ui and @spacemade/api packages.

Build each Admin product as a lightweight repo that installs or links both packages.

Keep product-specific schema, generated overlays, routes, and custom code in the product repo.

If you later discover stable cross-product modules, extract them into additional @spacemade/* packages.

For a CMS-style install system, see:

• docs/cms-quickstart.md
• docs/simple-cms-quickstart.md
• docs/gallery-quickstart.md
• docs/nft-quickstart.md
• docs/gpu-marketplace-quickstart.md
• docs/metaverse-quickstart.md