Learn what UtopiaSystem is and which business areas it supports.
Getting Started is the first page new team members should read before working on UtopiaSystem.
This page gives a high-level path for joining the project, understanding the system, setting up the tools, and knowing where to go next.
Start here to understand the system, the apps, the tools, and the first development path.
Learn what UtopiaSystem is and which business areas it supports.
Review Launcher, Personal Space, Work Space, HR, Finance, OE, Sales, and Tools.
Set up GitHub, Supabase, Vercel, npm, Nx, Playwright, PM2, and local requirements.
Use the reading order, checklist, and help notes before making larger changes.
The purpose of this page is to help new team members start with the right order.
A new developer should understand:
UtopiaSystem is an internal business system used to support employee self-service, HR operations, finance workflows, operational efficiency, approvals, reports, and internal tools.
The system is made of multiple apps and spaces. Each app focuses on a different business area.
The main applications are listed below.
| Application | Purpose |
|---|---|
| Launcher | Main home page where users choose apps and tools |
| Personal Space | Employee self-service such as claims, leave, overtime, and profile |
| Work Space | Approvals, team management, work operations, and Developer tools |
| HR Space | HR operations, recruitment, performance, and employee management |
| Finance Space | Supplier payments, claims verification, accounts, and credit management |
| Operation Efficiency Space | Warehouse, inventory, attendance, and operational tracking |
| Sales Space | Sales and order-related workflows |
| Tools | Supporting tools such as Fleet Tracker, Outreach, Replybox, and Asset Management |
New team members should read the documentation in this order.
This gives a balance between system understanding and practical development workflow.
The team uses several tools for development, deployment, database management, and collaboration.
| Tool | Used For |
|---|---|
| GitHub | Source code, branches, pull requests, and reviews |
| Supabase | Auth, database, storage, policies, and Edge Functions |
| Vercel | Frontend deployment |
| DigitalOcean | Backend deployment and container registry |
| Google Cloud | Google OAuth and sign-in configuration |
| Wiki.js | System and team documentation |
| Nx | Monorepo project management |
| npm | Dependency management |
| Playwright | End-to-end testing |
| PM2 | Local multi-app process management |
A new team member may need access to several systems.
| Access | Why It Is Needed |
|---|---|
| GitHub | To clone the repository, create branches, and open pull requests |
| Supabase | To inspect database, auth, storage, migrations, and policies |
| Vercel | To view frontend deployments and environment variables |
| DigitalOcean | To check backend deployments or container registry |
| Google Cloud | To manage OAuth or Google sign-in settings |
| Wiki.js | To read and update documentation |
| UtopiaSystem account | To test the actual app |
Access should be requested from the team lead or system admin.
The main repository is utopiaspace-core.
The repository contains the main apps, shared packages, docs, tools, and project configuration.
Before running the project locally, install the required tools.
npm install
cp .env.example .env
npm run setup:httpsAfter creating .env, fill in the real environment values. For detailed setup instructions, read Development Guide → Local Setup.
Use these commands during local development.
npm run devnpm run dev:stopnpm run dev:statusnpm run dev:logsFor detailed instructions, read Development Guide → Running the Apps.
The main local development ports are listed below.
| App | Port |
|---|---|
| Personal Space | 3000 |
| Finance Frontend | 3001 |
| HR Space | 3002 |
| Operation Efficiency Space | 3003 |
| Launcher | 3006 |
| Finance Backend | 8080 |
| OE Backend | 8081 |
Development work should normally start from development.
For details, read Team Onboarding → GitHub Guide.
A new team member can follow this checklist.
New team members should learn these areas first.
Advanced topics such as backend deployment, database migrations, and production configuration can be learned after the basics are comfortable.
If a new team member gets stuck, they should check the documentation first and include useful context when asking for help.
Getting Started gives new team members the first path into UtopiaSystem. The goal is to understand the system, get the right access, set up the repository, run the apps locally, and learn the team workflow before making larger changes.