engineXBETA

Developer Guide

Write your idea — engineX builds the app

Never written a line of code? That's fine. Describe the app you want in plain words — an AI assistant does the technical steps and builds it, right inside engineX. This guide walks you through it, word by word.

The easy way (AI) Do it by hand

Part 1 · Understand it

What is an “app” in engineX?

engineX is built on one idea: a shared shell + independent apps. The shell handles everything apps need, without exception — login, menus, a unified layout. You never rebuild that each time; you build only your app — HR, Marketing, Inspections — and it snaps onto the shell as an independent add-on, added or changed without affecting anything around it.

Building an app means three things: (1) create the app's folder, (2) plug it into the shell so its pages open, and (3) register it so it appears in the sidebar. Miss one and it won't show up. This guide does all three.

Honest note: building an app does involve editing a few files — it isn't truly “no code.” But you don't have to write that code yourself. The AI assistant below does it while you describe what you want in plain language.

Part 2 · Before you start

Get set up once

You install these five things one time. Take it slowly — each is a normal installer.

A computer
Mac, Windows, or Linux — that's all the hardware you need.
Node.js
The engine that runs engineX. Download the “LTS” version from nodejs.org and click through the installer.
pnpm
The tool that installs the project's building blocks. After Node, run: npm install -g pnpm
The engineX code
Get a copy of the project (your team will share it), open its folder, and run: pnpm install
Claude Code
The AI assistant that writes the code for you. Install it once, then open it inside the project folder.
Quick install of pnpm (after Node):
npm install -g pnpm
Recommended for beginners

The easy way — build it with Claude Code

Claude Code is an AI assistant that works inside the project and writes code for you. You type what you want in plain English or Arabic; it does the technical steps. To make it reliable, we've packaged the exact recipe as a “skill”.

The “Create an engineX app” skill
Download it, then drop the folder into your project's .claude/skills/ — Claude Code picks it up automatically.
Download skill (.zip)View as Markdown
Already working inside the engineX repo? The skill is built in — just ask Claude Code to “create a new engineX app” and it follows the recipe. The download is for taking it elsewhere or sharing it.

Copy-paste starter prompts

Paste any of these into Claude Code and change the details to fit your app.

Scaffold a whole new app
Create a new engineX product app. Slug: "library", name "Library" (Arabic "المكتبة"), category operations, icon BookOpen. It lets staff track books and who borrowed them. Do the full install flow: scaffold with create-app.sh, fill the bilingual manifest, wire it with install-app.js, register it in the database, add force-dynamic to the re-exports, and confirm it runs at http://localhost:3000/library and shows in the sidebar.
Add a page to your app
Add a page to my "library" app at /library/overdue that lists overdue books. Make it bilingual (Arabic + English), use PageHeader and Card from @platform/ui, and wire the client-shell re-export with force-dynamic.
Make the data persist
Give my "library" app a database model and API so books are saved: fields title, author, borrowedBy, dueDate. Make it org-scoped with requireOrgContext, add an additive migration, and give me a simple form to add a book.
When something breaks
I ran the app and got this error: <paste the full error here>. Explain in simple terms what's wrong and fix it.
Polish it (bilingual + RTL)
Check my "library" app: make sure every visible text has an Arabic translation and the layout looks correct in Arabic (right-to-left). Fix anything that's English-only or uses left/right instead of start/end.
Ship it
Walk me through deploying my "library" app to the stage environment, step by step, and tell me how to check it worked.

Tips for talking to Claude Code

  • Say who uses it and what it does — “a page for staff to log maintenance requests”.
  • Ask for one thing at a time, then build on it.
  • If something breaks, paste the full error back — that's usually all it needs.
  • Remind it to keep everything bilingual (Arabic + English).
  • Ask it to “show me it working” — it can run the app and confirm.
For the curious

The manual way — every step by hand

Want to understand each command? Here's the same result, done yourself.

1
Open a terminal
A terminal is a text window where you type commands. On Mac open “Terminal”, on Windows open “PowerShell”. Then go into the project folder.
2
Create the app skeleton
This asks a few questions (name, Arabic name, category, icon) and builds an empty app for you.
bash scripts/create-app.sh
3
Look at what was created
Your app now lives in apps/products/<your-slug>/. Two files matter most: lib/manifest.ts (its name and menu) and pages/page.tsx (its first screen).
4
Edit the menu (manifest)
Open lib/manifest.ts and list the pages you want in the sidebar — each with an English AND Arabic label. This is the app's table of contents.
5
Build your first page
Open pages/page.tsx and change the text/layout. Use the ready-made pieces from @platform/ui (PageHeader, Card, Button) so it matches the platform.
6
Plug it into the platform
This connects your app to the main shell so its pages actually open.
node scripts/install-app.js <your-slug>
7
Register it (so it appears)
The sidebar reads the database, not the code. This command tells the database your app exists and turns it on for every organization.
pnpm --filter @platform/db exec tsx prisma/install-all-apps.ts
8
Run it and open it
Start the app, then open the link in your browser. Log in, and your app is in the sidebar.
pnpm --filter @platform/client dev
# then open http://localhost:3000/<your-slug>
9
You built an app 🎉
That's it — it's a real, installed engineX app. From here you add more pages, save data, and refine the look (Claude Code can do all of it).
Two things people forget: every re-export page needs the line export const dynamic = "force-dynamic", and the sidebar only updates after the register step (step 7). If your app 404s or doesn't appear, it's almost always one of these.

Part 4 · Going further

Once your app exists

  • Save data: add a database model + API (org-scoped) and a migration — ask Claude Code, or see CLAUDE.md.
  • Add more pages: each needs a menu item + two client-shell re-exports (page and API).
  • Keep it bilingual and right-to-left safe (use start/end, not left/right).
  • Deploy to stage via a pull request to main — the platform builds it automatically.

Glossary

Plain-language definitions

Terminal — A text window where you type commands to the computer.
Slug — Your app's short lowercase id, used in its web address, e.g. “library”.
Manifest — A small file describing your app: its name, icon, and sidebar menu.
Component — A ready-made building block for the screen (a button, a card).
API — The behind-the-scenes part that saves and fetches your data.
Repository / repo — The folder holding all of engineX's code.
Deploy — Publishing your app so real users can use it.
Skill — A recipe you give Claude Code so it follows the right steps every time.
Prompt — The plain-language instruction you type to Claude Code.

Ready to build yours?

Download the skill, open Claude Code, and describe your idea. You'll have a working app in minutes.

Download the skill