Someli Platform — Cross-Repo Overview¶

This document is the map of the Someli platform across all nine repositories. Read this before opening any individual repo's audit subtree.

1. What Someli is¶

Someli is a B2B SaaS for AI-driven social media content management. Customers (typically SMBs and agencies) upload brand assets and a brief, the platform generates social media posts via AI (text + image), customers approve and schedule, and the platform publishes to Facebook, Instagram, LinkedIn, TikTok, and X across recurring schedules.

The platform also has: - An internal designer tool used by Someli's content team to create and maintain template libraries - An admin console used by Someli's customer-success and ops staff

So the platform has three user audiences, each with its own UI:

Audience	Frontend repo	Backend repo	Hostname (typical)
Customer (paying user)	`someli-platform`	`someli-api`	app.someli.ai
Internal designer / content ops	`Someli-Designer`	`designer-api`	(internal)
Internal admin / customer success	`admin_console_R`	`Someli-admin-api`	admin.someli.ai

2. The nine repositories¶

2.1 The three product pairs (six canonical repos)¶

┌────────────────────────────┐         ┌────────────────────────────┐
│   Customer app             │         │   Customer app             │
│   FE: someli-platform      │ ◀────▶ │   BE: someli-api           │
│   Nuxt 2 + Vue 2 (SPA)     │         │   Express + MySQL          │
│   + Polotno editor         │         │   ~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            │         │   Admin console            │
│   FE: admin_console_R      │ ◀────▶ │   BE: Someli-admin-api     │
│   Vite + React + shadcn/ui │         │   Express + MySQL          │
│   ~10 pages                │         │   ~40 endpoints            │
└────────────────────────────┘         └────────────────────────────┘

All three backends share the same server.js + routes/routes.js + actions/actions.js + helper/ + modules/dbDriver/ skeleton. The skeleton came from someli-api and was copy-pasted into designer-api and Someli-admin-api early on; the three forks then diverged. See CODE-OVERLAP-MATRIX.md for the file-by-file delta.

2.2 The three supporting repos¶

Repo	What it is	Source-of-truth status
`someli-dashboard-be`	A standalone extraction of `someli-api/dashboard/` — runs on port 6001, mounts `/dashboard/`, switches to `mock/` in `NODE_ENV=development`. In production it's still mounted inside* the main `someli-api` process via `someli-api/dashboard/`.	Diverging fork: 3 of 4 files differ from `someli-api/dashboard/`. Treated as a sandbox / standalone-runnable copy, not yet the source of truth.
`someli-mono-repo`	Snapshot that combines `someli-api` (→ `backend/`) and `someli-platform` (→ `frontend/`) into a single tree.	Read-only snapshot, last synced 2026-01-20. 333 of `someli-platform`'s files diverge from canonical. Do not edit here.
`someli-project`	Extends `someli-mono-repo` by also vendoring the admin and designer pairs under `backend/{admin,app,designer}-backend/` and `frontend/{admin,app,designer}-frontend/`.	Read-only snapshot, last synced 2026-01-23. Mostly identical to the canonical standalones (admin and designer pairs match cleanly; the `app-` pair is the same stale snapshot as `someli-mono-repo`). Do not edit here.*

The supporting repos exist to satisfy mono-repo / project-tree workflows (probably for tooling that doesn't deal well with cross-repo navigation, or for IDE-wide search). They are not rebuilt from canonical on every merge — they drift.

3. Canonical vs derived¶

When the same code exists in multiple places, always edit the canonical copy. This table is the authority:

Concern	Canonical repo	Derived locations (do not edit)
Main app backend code	`someli-api`	`someli-mono-repo/backend`, `someli-project/backend/app-backend`
Main app frontend code	`someli-platform`	`someli-mono-repo/frontend`, `someli-project/frontend/app-frontend`
Designer backend code	`designer-api`	`someli-project/backend/designer-backend`
Designer frontend code	`Someli-Designer`	`someli-project/frontend/designer-frontend`
Admin backend code	`Someli-admin-api`	`someli-project/backend/admin-backend`
Admin frontend code	`admin_console_R`	`someli-project/frontend/admin-frontend`
Dashboard analytics service code	`someli-api/dashboard/` (the in-process copy is the prod one)	`someli-dashboard-be` (standalone copy, used for local dev / future extraction)

This produces an unusual edge case for the dashboard: the standalone repo has diverged slightly from the in-process copy. Pick a direction and reconcile — see someli-dashboard-be/README.md.

4. Stack-at-a-glance¶

Layer	Tech	Repos
Backend language	Node.js (CommonJS, no TS)	someli-api, designer-api, Someli-admin-api, someli-dashboard-be
Backend framework	Express 4.x	same
Async runtime patterns	mixed: `mysql` callback API + `sync-mysql` (blocking) + `mysql2/promise`	same
Background jobs	standalone `job_*.js` scripts run by PM2 (no queue/broker)	someli-api (~108 jobs), designer-api (~57 jobs)
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)	someli-api, designer-api, someli-platform, Someli-Designer
Frontend (customer)	Nuxt 2.18.1 / Vue 2.7.16 / Vuex 3 / Bootstrap-Vue, SPA mode	someli-platform, Someli-Designer
Frontend (admin)	Vite 5 / React 18 / TS 5 / shadcn/ui / Tailwind / Radix UI	admin_console_R
Editor	React 18 + MobX-State-Tree + Polotno (forked twice across `someli-platform/polotno-editor` and `Someli-Designer/polotno-editor`)	someli-platform, Someli-Designer
Database	MySQL (shared schema across all backends; an audit-time snapshot is captured at `someli-api/someli-schema.sql` under this audit tree — not in any of the cloned repos)	all backends
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 (each via custom OAuth flow)	someli-api
Notifications	Slack (someli-api), MS Teams webhook (designer-api)	as noted
Object storage	AWS S3 (two buckets across two regions)	all backends
Deployment FE	Docker + nginx + Nuxt SPA, `node_modules` mounted from EFS at runtime	someli-platform, Someli-Designer
Deployment BE	Docker + nginx + PM2 (`ecosystem.config.js` in someli-api), Jenkins SSH-deploy to AWS Lightsail	all backends
CI/CD	Jenkins (primary, all repos) + GitHub Actions (newer; only someli-api so far)	as noted
Branch model	`feature` → `dev_` → `uat_` → `main` (someli-api uses `dev_api`/`uat_api`/`main`; someli-platform uses `dev_app`/`uat_app`/`main`; smaller repos use plain `dev`/`uat`/`main`)	all

5. Where to look first¶

If the user asks you to…	Look in
fix a customer-facing UI bug	`someli-platform/`
fix a published-post issue (FB/IG/LI/TT)	`someli-api/jobs-inventory.md`, then the relevant `job_*_publish.js`
trace AI content generation	`someli-api/agents-and-ai.md` + `someli-api/content-pipeline.md`
trace RAG / knowledge-base lookups	`someli-api/rag-pipeline.md`
debug a Paddle webhook	`someli-api/API-inventory.md` § paddle, then `routes/paddle.js`
work on the designer (template editor for staff)	`Someli-Designer/` (FE) + `designer-api/` (BE)
work on the customer designer (editor inside the app)	`someli-platform/06-polotno-integration.md` + `someli-platform/polotno-editor/`
admin / support tooling	`admin_console_R/` (FE) + `Someli-admin-api/` (BE)
analytics dashboards (impressions, growth)	`someli-api/dashboard-analytics.md` (the `someli-api/dashboard/` directory)
deploy a new env	`someli-api/deployment.md` (the patterns mirror across repos) + `someli-api/first-deployment.md`

6. Cross-cutting concerns to know about¶

The shared MySQL database. All four backends point at the same DB. The source of truth is the live MySQL instance; an audit-time snapshot is captured at someli-api/someli-schema.sql under this audit tree (it is not committed in any of the cloned repos). Cross-team work must coordinate on schema migrations (there is no migration framework — schema changes are run manually).
The shared helper/ lineage. someli-api/helper/ was the original copy; Someli-admin-api/helper/ and designer-api/helper/ started as copies and diverged. Files like ragProcess.js, revokeToken.js, tokenGenerator.js, webScraping.js are byte-identical across someli-api and Someli-admin-api today; aiLogics.js, helper.js, constants.js have hundreds of lines of drift. See CODE-OVERLAP-MATRIX.md.
Token format and apptype header. All three frontends send a base64 Apptype header so backends can identify which app the request came from. Some endpoints behave differently per Apptype. The customer and designer FE use the @nuxtjs/auth local strategy; the admin FE uses a hand-rolled AuthContext with localStorage token.
Two coexisting CI systems. Jenkins is the operational one (deploys to Lightsail via SSH + PM2). GitHub Actions has been introduced for someli-api only and currently mirrors what Jenkins does. Don't assume parity.
The two Polotno forks. someli-platform/polotno-editor/ and Someli-Designer/polotno-editor/ started from the same source but have diverged — there are renamed files (brandkitpanel.js vs brandkitPanel.js), entirely-new panels in one but not the other, and an additional customTextSection/, common/, helper/ subfolders only in the customer copy. Edits to one are not automatically reflected in the other.
The dashboard-be split-brain. someli-api/dashboard/ is the one production runs. someli-dashboard-be is a standalone copy used for local dev with mocks. They drift — see someli-dashboard-be/README.md.
The Apptype and role-typed UI gating. The designer FE (Someli-Designer/components/Navbar.vue + recent commit 074b9ec) restricts nav items by role_type and the backend has corresponding access checks. The role taxonomy (SUPER_ADMIN, ADMIN, ACCOUNT_MANAGER, DEVELOPER, DESIGNER, etc.) is in admin_console_R/src/config/env.ts and replicated on backends.

7. Where the platform is going¶

Evidence in the repos suggests modernisation in progress:

The newest UI repo (admin_console_R, started ~2025-Q4) uses Vite + React + TypeScript + shadcn/ui — a complete departure from the Nuxt 2 / Vue 2 stack used by the older customer and designer FEs. This is a forward direction: future UIs will likely follow this stack.
The admin backend (Someli-admin-api) is a much smaller, cleaner cut of the same Express skeleton (only ~2400 LoC of routes vs ~22000 in someli-api). It's not yet a destination for code lifted out of someli-api, but it sets a pattern for what a cleanly-scoped service can look like.
The standalone someli-dashboard-be and the GitHub-Actions deploy for someli-api are early signals of breaking the monolith into smaller deployable units.
someli-mono-repo and someli-project exist but are stale; the team appears to be using them as snapshots for analysis (e.g., this audit) rather than as active development trees.

A reader following these signals should expect, over the next 12–24 months: continued extraction of services out of someli-api, gradual migration of UIs to the Vite/React/shadcn stack, and unification of CI on GitHub Actions.

For the file-by-file overlap details, continue to CODE-OVERLAP-MATRIX.md.

For component-level audits, dive into the per-repo subtrees from the README.md index.