01 — Platform tour¶

Before you open any one repo, understand the whole shape of the platform. Ten minutes here saves hours of confusion later.

What Someli is, in one paragraph¶

Someli is a B2B SaaS for AI-driven social-media content management. Customers (typically small businesses and marketing agencies) upload brand assets and a content brief; the platform generates social-media posts via AI — text and image — and schedules them; the customer approves them; the platform publishes to Facebook, Instagram, LinkedIn, TikTok, and X across recurring schedules. Customers pay through Paddle (sandbox + production); Stripe is a legacy billing path.

The platform also has:

An internal designer tool used by Someli's content-ops staff to author and maintain template libraries (the templates the customer-facing AI builds posts from).
An admin console used by Someli's customer-success and ops staff to manage customer accounts, support, personnel, and affiliate marketing.

Three products, six repos, one database¶

┌─────────────────────────────────┐       ┌─────────────────────────────────┐
│  Customer app                   │       │  Customer app                   │
│  FE: someli-platform            │ ◀───▶ │  BE: someli-api                 │
│  Nuxt 2 + Vue 2 SPA + Polotno   │       │  Express + MySQL                │
│                                 │       │  ~728 endpoints / ~108 jobs     │
└─────────────────────────────────┘       └─────────────────────────────────┘

┌─────────────────────────────────┐       ┌─────────────────────────────────┐
│  Designer (internal)            │       │  Designer (internal)            │
│  FE: Someli-Designer            │ ◀───▶ │  BE: designer-api               │
│  Nuxt 2 + Vue 2 + Polotno       │       │  Express + MySQL                │
│  ~73 pages                      │       │  ~269 endpoints / ~57 jobs      │
└─────────────────────────────────┘       └─────────────────────────────────┘

┌─────────────────────────────────┐       ┌─────────────────────────────────┐
│  Admin console (internal)       │       │  Admin console (internal)       │
│  FE: admin_console_R            │ ◀───▶ │  BE: Someli-admin-api           │
│  Vite + React + TS + shadcn/ui  │       │  Express + MySQL                │
│  ~10 pages                      │       │  ~40 endpoints                  │
└─────────────────────────────────┘       └─────────────────────────────────┘
                  │
                  ▼
       ┌─────────────────────────┐
       │  ONE shared MySQL DB    │
       │  (all three BEs talk    │
       │   to the same database) │
       └─────────────────────────┘

All three backends were forked from someli-api's skeleton (Express + server.js + routes/routes.js + actions/ + helper/ + modules/dbDriver/) at different points in time. They have drifted since. Same-named files between repos are not byte-identical — see CODE-OVERLAP-MATRIX.md for the file-by-file delta.

Key consequence: a bug fix to helper/aiLogics.js in someli-api does not automatically apply to Someli-admin-api/helper/aiLogics.js. They might look 95% identical, but the 5% drift is real. Always check both when touching shared-lineage files.

What the names mean (and the casing quirks)¶

Name in this tree	What it is	Stack
`someli-api`	Customer-app backend	Express + MySQL
`someli-platform`	Customer-app frontend ("platform" = customer-facing SaaS platform)	Nuxt 2 + Vue 2 SPA
`designer-api`	Internal designer backend	Express + MySQL
`Someli-Designer`	Internal designer frontend (note the capital `S` and `D`)	Nuxt 2 + Vue 2 + Polotno
`Someli-admin-api`	Admin backend (note the capital `S`, lowercase `admin-api`)	Express + MySQL
`admin_console_R`	Admin frontend (the `_R` stands for "React"; this is the only modern-stack repo)	Vite + React + TS + shadcn/ui

The casing is inconsistent because the repos were named by different people over the years. Do not "fix" the names — the GitHub URLs, deployment scripts, and references in dozens of docs all depend on the existing capitalisation.

Three supporting / snapshot repos (read-only)¶

There are three more repos in the working directory that you may stumble across:

Repo	What it is	Status
`someli-dashboard-be`	A standalone Express service (port 6001) that mirrors `someli-api/dashboard/`. Exists so local dev can run the analytics dashboard against mock data without spinning up the whole `someli-api`.	Drifting fork. In production, the in-process copy inside `someli-api` is what runs.
`someli-mono-repo`	A read-only snapshot combining `someli-api` (→ `backend/`) and `someli-platform` (→ `frontend/`).	Snapshot, last synced 2026-01-20. Hundreds of files behind canonical. Never edit.
`someli-project`	A read-only snapshot combining all six product repos under `backend/{admin,app,designer}-backend/` and `frontend/{admin,app,designer}-frontend/`.	Snapshot, last synced 2026-01-23. Never edit.

Rule: edit only the six canonical product repos. The snapshot repos exist for tooling that doesn't deal well with cross-repo navigation; they decay over time.

Stack-at-a-glance¶

Layer	Tech	Repos
Backend language	Node.js 20.x (CommonJS — `require`/`module.exports`, no TypeScript)	all four backends
Backend framework	Express 4.x	all four backends
Async runtime	mixed: callback `mysql` + blocking `sync-mysql` + promise `mysql2/promise`	all four backends
Background jobs	standalone `job_*.js` scripts, scheduled by PM2 + `node-cron` (no queue/broker)	`someli-api` (~108), `designer-api` (~57)
AI providers	AWS Bedrock (Claude, Llama, Nova), Google Vertex / Gemini, OpenAI	`someli-api`, `designer-api`, `Someli-admin-api`
RAG / vector	Google Cloud RAG (Vertex)	`someli-api`
Image generation	Polotno SDK (`polotno-node` server-side + `polotno` client-side)	all four product pairs
Frontend (customer + designer)	Nuxt 2.18 / Vue 2.7 / Vuex 3 / Bootstrap-Vue / SPA mode (`ssr: false`)	`someli-platform`, `Someli-Designer`
Frontend (admin)	Vite 5 / React 18 / TS 5 / shadcn/ui / Tailwind 3 / Radix UI	`admin_console_R`
Editor (visual)	React 18 + MobX-State-Tree + Polotno (forked into two copies)	`someli-platform/polotno-editor/`, `Someli-Designer/polotno-editor/`
Database	MySQL (one schema; audit-time snapshot at `audit/someli-api/someli-schema.sql` — documentation-only, not committed in any cloned repo)	all four backends share it
Billing	Paddle (sandbox + prod), Stripe (legacy)	`someli-api`, `Someli-admin-api`
Email	SendGrid	`someli-api`, `designer-api`, `Someli-admin-api`
Social publishing	Facebook / Instagram / LinkedIn / TikTok / X (custom OAuth flows per platform)	`someli-api`
Notifications	Slack (`someli-api`), MS Teams webhook (`designer-api`)	as listed
Object storage	AWS S3 (two buckets across two regions)	all backends
Deployment	Docker + nginx + PM2; Jenkins SSH-deploy to AWS Lightsail	all backends
CI	Jenkins (everywhere) + GitHub Actions (only `someli-api` so far)	as listed

Vue 2 reached end-of-life in December 2023. The customer and designer FEs are on borrowed time for security patches. The admin FE (admin_console_R, React + Vite + TS) is the direction the platform is moving in. Don't bring new dependencies into the Vue 2 apps lightly.

Three cross-cutting concepts you MUST internalise¶

1. The shared MySQL database¶

All four backends point at the same MySQL instance in production. There is no service ownership of tables — tMember, tPost, tAccount, etc. are read and written by all four. Schema changes are coordinated by the team manually; there is no migration framework.

Consequence for you: when you change a table's shape, you may break a job or endpoint in another repo. Always grep across all four backends before altering a schema.

2. The `Apptype` header¶

All three frontends send a base64-encoded Apptype header on every API request, so backends can identify which app the request came from. Some endpoints behave differently per Apptype. The customer FE and the designer FE use @nuxtjs/auth (the local strategy). The admin FE uses a hand-rolled AuthContext with localStorage token storage.

Consequence for you: you cannot just point the admin FE at someli-api and expect things to work. The Apptype is part of authorisation in many places.

3. Two Polotno editor forks that have drifted¶

someli-platform/polotno-editor/ and Someli-Designer/polotno-editor/ both started from the same source, but they have diverged. There are renamed files (brandkitpanel.js vs brandkitPanel.js), entirely-new panels in one but not the other, and subfolders (customTextSection/, common/, helper/) that exist only in the customer copy.

Consequence for you: a change to the customer Polotno editor is not automatically reflected in the designer Polotno editor. If you fix a bug in one, decide whether the other needs the same fix and port it manually.

Branching model (high-level — full detail in `02-git-workflow.md`)¶

Every repo follows the same shape:

feature-branch  →  PR into  dev_*  →  merge into  uat_*  (QA)  →  merge into  main  (prod)

Per-repo branch names differ slightly:

Repo	dev branch	uat branch	prod branch
`someli-api`	`dev_api`	`uat_api`	`main`
`someli-platform`	`dev_app`	`uat_app`	`main`
`Someli-Designer`	`dev_des_app`	`uat_des_app`	`main`
`designer-api`	`dev`	`uat`	`main`
`Someli-admin-api`	`dev`	`uat`	`main`
`admin_console_R`	`dev`	`uat`	`main`

Never commit directly to dev_* / uat_* / main. Always feature-branch and PR.

Where to look first (cross-platform routing table)¶

If the user asks you to…	Open this first
Fix a customer-facing UI bug	`someli-platform/` + `../audit/someli-platform/` (audit) + `someli-platform/` (onboarding)
Fix a published-post issue (FB / IG / LI / TT / X)	`../audit/someli-api/jobs-inventory.md` → the relevant `job_*_publish.js`
Trace AI content generation	`../audit/someli-api/agents-and-ai.md` + `../audit/someli-api/content-pipeline.md`
Trace RAG / knowledge-base lookups	`../audit/someli-api/rag-pipeline.md`
Debug a Paddle webhook	`../audit/someli-api/API-inventory.md` § paddle → `someli-api/routes/paddle.js`
Work on the internal designer tool	`Someli-Designer/` (FE) + `designer-api/` (BE)
Work on the customer's in-app editor	`someli-platform/polotno-editor/` + `../audit/someli-platform/06-polotno-integration.md`
Admin / support tooling	`admin_console_R/` (FE) + `Someli-admin-api/` (BE)
Analytics dashboards (impressions, growth)	`../audit/someli-api/dashboard-analytics.md` — production runs the in-process copy inside `someli-api/dashboard/`
Deploy a new env	`../audit/someli-api/deployment.md` + per-repo `build-and-deploy.md`
Cross-repo refactor / shared-helper change	Read `../audit/CODE-OVERLAP-MATRIX.md` first.

Mental model in one sentence¶

"Three FEs and three BEs, all pointing at one MySQL. The admin pair is the modern (React/Vite) one; the other two pairs are Nuxt 2/Vue 2 SPAs. Three of the four BEs were forked from the customer BE and have drifted."

If you remember that, you will never be lost.

Next¶

→ 02-git-workflow.md — the team's branch/PR workflow, what NOT to commit to, how the snapshots fit in.

Then pick the module you'll work on first and open its 01-setup.md.