Skip to content

Onboarding — Welcome to Someli Engineering

This tree exists for one purpose: get a new junior developer from a fresh laptop to their first merged pull request, across any of the six Someli product repos, without having to interrupt a senior every five minutes.

If you are that new developer — read this page first, top to bottom. It is short on purpose.

What documentation exists, and which one is this?

The Someli docs are organised into three layers. Use the right one for the task you have:

Layer Lives in Purpose When you need it
Description someli-doc/<repo>/ Audit-style reference: architecture, security, data flows, every env var, every endpoint, every job When you are fixing a bug or adding a feature and need to understand "how does this part of the system actually work?"
Code inspection someli-doc/code-inspect/ Concrete code-level bugs and quality issues with file:line citations When you are hunting a known bug or want a list of "things to clean up if I touch this file"
Onboarding (you are here) someli-doc/onboard/ Workstation setup → tech stack → first-day code tour → "where do I look when…?" When you are new, or new to a particular module, and want a guided path rather than a reference

The description layer is comprehensive but assumes you already know the platform shape. The inspection layer is narrow and bug-hunting. The onboarding layer is the only one written to be read front-to-back. Start here, graduate to the others as you need depth.

What you will end up able to do

By the end of this tree, you should be able to:

  1. Set up your workstation — install Node, MySQL, Chromium deps, GitHub access, an editor that respects the codebase style. → 00-workstation-setup.md
  2. Understand the platform's shape — three products, six repos, one shared MySQL, why the same helper/ file exists three times. → 01-platform-tour.md
  3. Use the team's git/PR workflow — dev_* → uat_* → main, what NOT to commit to (snapshot repos), how to open a PR. → 02-git-workflow.md
  4. Run, navigate, and contribute to any specific module — by following the five-file walkthrough in that module's subdirectory.

The six modules

Customer-facing app (the paying product)
├── someli-platform/     ← Nuxt 2 / Vue 2 SPA frontend
└── someli-api/          ← Express + MySQL backend (the largest service in the platform)

Internal designer tool (used by Someli's content team)
├── Someli-Designer/     ← Nuxt 2 / Vue 2 + Polotno frontend
└── designer-api/        ← Express + MySQL backend

Admin console (used by Someli's customer-success and ops staff)
├── admin_console_R/     ← Vite + React + TypeScript + shadcn/ui frontend  (the modern one)
└── Someli-admin-api/    ← Express + MySQL backend

Each module has its own subdirectory in this tree. Inside each subdirectory you will find five files, always in the same order:

File What it covers
01-setup.md What to clone, what to install, what env vars you need, how to start the dev server
02-stack.md The exact tech stack — versions, libraries, why each choice matters
03-architecture.md The shape of the code — entry point, folders, how a request flows through
04-getting-started.md Your first contribution: pick a tiny task, find the file, change it, run it, PR it
05-where-to-look.md "When something is wrong with X, the answer lives in Y" — a routing table for issues

Per-module READMEs index the five files.

You don't need to read every module. Read in this order, stopping wherever you have enough:

  1. Cross-cutting (everyone reads these):
  2. 00-workstation-setup.md
  3. 01-platform-tour.md
  4. 02-git-workflow.md
  5. The module you'll work on first. Whoever onboarded you will tell you which. If nobody did:
  6. Joining the customer-app team? → someli-platform/ (FE) and someli-api/ (BE).
  7. Joining the designer/content-ops team? → Someli-Designer/ (FE) and designer-api/ (BE).
  8. Joining admin/ops tooling? → admin_console_R/ (FE) and Someli-admin-api/ (BE).
  9. Adjacent modules, on demand. The shared MySQL and shared helper/ lineage mean a customer-app developer will sometimes need to read into designer-api/ or Someli-admin-api/ to chase a bug. Don't preload them — open the relevant 5-file walkthrough when the time comes.

"Where am I in the bigger picture?"

                          [you]
                            │
                ┌───────────┴───────────┐
                ▼                       ▼
        Cross-cutting docs        Per-module docs
                │                       │
   ┌────────────┼────────────┐          │
   ▼            ▼            ▼          ▼
 00 setup   01 tour      02 git     six modules × 5 files
   │            │            │          │
   │            │            │          ▼
   │            │            │     someli-platform/   ┐
   │            │            │     someli-api/         │
   │            │            │     Someli-Designer/    │ each has
   │            │            │     designer-api/       │ 01..05.md
   │            │            │     admin_console_R/    │
   │            │            │     Someli-admin-api/   ┘
   ▼            ▼            ▼          │
   └────────────┴────────────┴──────────┘
                            │
                            ▼
                  Description docs
                  (someli-doc/<repo>/)
                            │
                            ▼
                  Code inspection
                 (someli-doc/code-inspect/)

How to use this tree

  • Read top-to-bottom, not by jumping. Each section assumes you read the one above.
  • Run every command as you go. Reading without running leaves you with a false sense of readiness.
  • When a file says "Verify with the team", that is a literal instruction — Slack the team and get the answer before continuing.
  • Update these docs when you find them wrong. You are the most recent person to onboard; you know better than anyone where the gaps are. A PR to someli-doc/onboard/ from an onboarding junior is a welcome PR, not a presumptuous one.

Pointers

Document metadata
Tree someli-doc/onboard/
Audience New developer, junior level, ≥1 year Node/JS experience but new to Nuxt 2 / Polotno / the Someli platform
Author Initial draft via Claude Code, 2026-05-19
Re-verify After major refactors or onboarding feedback; at minimum every 6 months