Operating guide
One product. A deployment for each company.
Moment Plus maintains the reusable product and operates its deployments. Each company receives a branded website and staff dashboard with isolated business data.
Run the local workspace
From the repository root, run corepack pnpm dev, then open the platform home. On Windows, you can also double-click Start Osool.cmd. The home page links to the company website and dashboard.
The apps still use separate local ports because they have independent servers and authentication. The launcher manages those servers; you only need to bookmark the platform home. On hosted deployments, users open company domains and do not manage ports.
Keep the terminal open. Ctrl+C stops the servers started by this launcher. Use corepack pnpm dev -- --only admin when you only need the platform.
Who manages what?
- Platform administrator: registers company deployment metadata and checks the registry. Platform access does not grant access to company records.
- Company administrator: manages projects, content, people, and reports through that company’s dashboard.
- Operator/developer: provisions infrastructure, configures secrets, applies migrations, deploys releases, and verifies backups.
What is reusable, and what changes?
| Area | Ownership | How it works |
|---|---|---|
| Database and migrations | Shared | Every company uses the same organization schema, installed in its own database. |
| Authentication policy | Shared | Invitation-only organization authentication; accounts and sessions stay in each company database. |
| UI components | Shared | Consume @osool/ui. Improve common components once; release each app independently. |
| Brand and content | Company-specific | Names, logos, colors, Arabic/English copy, domains, and published content. |
| Page composition and unique workflows | Company-specific | Keep unique layouts and behavior in the company app. Extract common operations when a second company needs them. |
| Infrastructure and secrets | Isolated | Separate staging and production databases, storage, hosting projects, credentials, and backups. |
Today, the database model, authentication policy, and UI are reusable packages. Most dashboard workflows still live in Sustainability Global’s app. A second company needs deliberate extraction of the workflows it shares; duplicating the whole dashboard would create two versions to maintain.
New company checklist
From agreement to launch
- Define the scope. Agree on brand, languages, pages, workflows, domains, who administers the company, and support/backup requirements.
- Create the company app shells. Add website and dashboard workspaces under the company slug. Reuse shared packages and extract the common workflows required by this second consumer. Keep its unique composition local.
- Register the company. Save its bilingual identity and intended staging endpoints in the platform registry. Registration does not create infrastructure.
- Provision staging. Create the company’s Neon database, Vercel website/dashboard projects, and public/private R2 buckets. Configure scoped runtime credentials and separate migration credentials.
- Migrate and deploy. Apply the shared organization migrations to the selected staging database. Deploy the website and dashboard with their own environment values.
- Initialize the first company administrator. Use the documented short-lived bootstrap protocol. Invitations and company accounts belong to the company database.
- Accept staging. Verify sign-in, role restrictions, uploads, publication, website cache invalidation, and any contracted reports or messaging.
- Create production separately. Repeat provisioning with production resources and domains, verify recovery, and deploy the tested release. Register production endpoints separately.
- Operate the release. Track version and health, back up the environment, rotate credentials, and roll out shared changes through staging before production.
What the platform does today
- First platform administrator setup, sign-in, and sign-out.
- Authenticated company registration, deployment links, and previously recorded health observations.
- A local application launch point and this operating guide.
What still requires an operator
Provider provisioning, app scaffolding, additional deployment registration, bootstrap dispatch, health polling, account recovery/additional platform administrators, and deployment automation still require operator tooling. The repository contains database and bootstrap building blocks, but these are not a finished one-click onboarding service.
Release and maintenance
For a brand-only change, verify and deploy that company’s apps. For a shared feature, verify every affected consumer, release to one staging company, then deploy each approved company independently. Apply schema migrations with the migration role, using the registered target list. Keep migrations backward compatible with apps that have not yet been released.
The detailed operator references live in the repository: docs/application_operations.md, docs/infrastructure_provisioning.md, and docs/organization_database.md.