`someli-doc/` — Someli platform documentation¶

The documentation tree for the Someli social-media-management platform: three customer-facing and internal products built from nine separately-versioned git repositories under the Someli-ai GitHub organisation.

If you've just landed here, the question to ask yourself is: what do I need this documentation for? That answer maps to one of three subtrees:

You are…	Open this	Then dive into
A new developer, setting up your workstation and aiming for your first PR	`onboard/`	A specific module's 5-file walkthrough
Building, fixing, or reasoning about a feature and need the full picture of how a repo works	`audit/`	The relevant per-repo audit subtree (`audit/<repo>/`)
Bug-hunting or doing a code-quality pass — you want concrete code-level findings with `file:line` citations	`code-inspect/`	The relevant per-repo inspection file

That's it. Three subtrees, three audiences. They cross-link to each other but each is self-contained.

The three subtrees in one paragraph each¶

`audit/` — Description¶

The full audit-style reference. Per-repo subtrees (audit/<repo>/) mirror the same shape — architecture, security, deployment, dependencies, endpoint and job inventories, data model, AI/RAG pipelines where relevant, observability, testing, and a numbered verification report. Plus cross-cutting documents at the root of the subtree:

audit/PLATFORM-OVERVIEW.md — the mental map: three products, nine repos, how they fit together. Read this first if you're new to the platform.
audit/CODE-OVERLAP-MATRIX.md — what's shared across repos, what was copy-pasted, what's diverged. Open this before any change to a shared helper.
audit/architecture-findings.md — cross-repo architectural anti-patterns and the design pressures behind the bug findings in code-inspect/.
audit/_meta/AUDIT_GUIDE.md — the methodology the per-repo audits follow.

`code-inspect/` — Inspection¶

Concrete, reproducible code-level bugs and quality issues, per repo, with file:line citations. Narrow lens — it does NOT re-litigate architecture, security posture, or deployment (those live in audit/). One report per product repo:

code-inspect/
├── someli-api.md
├── someli-platform.md
├── designer-api.md
├── Someli-Designer.md
├── Someli-admin-api.md
└── admin_console_R.md

Findings are confidence-filtered: a short report means few real issues were found, not a shallow inspection.

`onboard/` — Onboarding¶

The only subtree written to be read front-to-back, by a new developer joining the team. Workstation setup, platform tour, git workflow — then a per-module five-file walkthrough that takes you from clone to merged PR. Junior-friendly tone, explicit warnings, "where to look when…" routing tables.

Module trees in onboard/:

onboard/
├── 00-workstation-setup.md
├── 01-platform-tour.md
├── 02-git-workflow.md
├── someli-api/         (BE — customer)
├── someli-platform/    (FE — customer)
├── designer-api/       (BE — designer)
├── Someli-Designer/    (FE — designer)
├── Someli-admin-api/   (BE — admin)
└── admin_console_R/    (FE — admin)

How they relate¶

                       README.md  (you are here)
                            │
        ┌───────────────────┼───────────────────┐
        ▼                   ▼                   ▼
    audit/              code-inspect/        onboard/
   (reference)          (bug findings)      (guided walkthrough)
        │                   │                   │
        │  per-repo         │  per-repo         │  per-module
        │  description      │  inspection       │  setup → first PR
        │                   │                   │
        └─────────┬─────────┴─────────┬─────────┘
                  │                   │
              cross-links         cross-links
                  │                   │
                  ▼                   ▼
                onboard/ links into audit/ and code-inspect/
                audit/  links into code-inspect/
                code-inspect/ links back into audit/

The three subtrees overlap on subject but differ on intent:

audit/ asks "how does this work?"
code-inspect/ asks "what's broken right here, at this line?"
onboard/ asks "what do I do, and in what order?"

When you need depth, you can cross from one to another via the links. When you need a single answer, pick the right tree first.

Repository inventory (quick reference)¶

The six canonical product repos:

Pair	Frontend	Backend	Stack
Customer app	`someli-platform`	`someli-api`	Nuxt 2 / Vue 2 SPA · Express + MySQL
Designer (internal)	`Someli-Designer`	`designer-api`	Nuxt 2 / Vue 2 + Polotno · Express + MySQL
Admin console (internal)	`admin_console_R`	`Someli-admin-api`	Vite + React + TS + shadcn/ui · Express + MySQL

Three supporting / snapshot repos (covered in audit/ for completeness — generally not edited):

someli-dashboard-be — standalone copy of someli-api/dashboard/, drifts from canonical.
someli-mono-repo — read-only snapshot of someli-api + someli-platform.
someli-project — read-only snapshot of all six product repos.

The full repo map: audit/PLATFORM-OVERVIEW.md.

Reading order for first-timers¶

This file (you've done that).
audit/PLATFORM-OVERVIEW.md — five minutes; the mental map.
Pick your role:
New engineer setting up to contribute → onboard/README.md.
Senior auditor / due-diligence reader → audit/README.md and then per-repo subtree.
Bug hunter → code-inspect/README.md.

Maintaining this tree¶


Last reorganised	2026-05-19 (three-pillar layout: `audit/` + `code-inspect/` + `onboard/`)
Audit content captured at	2026-05-17
Re-verify	Every 6 months, or after a major platform refactor
Methodology	`audit/_meta/AUDIT_GUIDE.md`

When updating documentation:

audit/ — change the canonical content in audit/<repo>/; do not edit the same content in the snapshot repos (someli-mono-repo, someli-project).
code-inspect/ — rerun the inspection process after major refactors; line numbers drift fast.
onboard/ — the most recently-onboarded engineer is the best author of fixes here. Onboarding-PRs from juniors are welcome.

Building HTML output¶

The docs render to a static HTML site at html/ that opens directly in a browser via file:// — no web server required. The site is generated with mkdocs.

One-time setup¶

# Install mkdocs + the Material theme + the awesome-pages plugin.
# (Debian/Ubuntu Python 3.12 needs pipx because of PEP 668.)
pipx install mkdocs
pipx inject mkdocs mkdocs-material
pipx inject mkdocs mkdocs-awesome-pages-plugin
# macOS / other Linux:
#   pip install --user mkdocs mkdocs-material mkdocs-awesome-pages-plugin

Build¶

cd someli-doc
mkdocs build
# Output: someli-doc/html/index.html

Open someli-doc/html/index.html in any browser to read the rendered docs. All internal links (audit ↔ code-inspect ↔ onboard) work offline over file://.

What's where¶

mkdocs.yml — config (Material theme with light/dark toggle, top-level tabs, code-copy buttons, link validation, use_directory_urls: false so URLs work over file://).
docs/ — a thin shim of symlinks pointing at README.md, audit/, code-inspect/, onboard/. Exists because mkdocs forbids site_dir from being inside docs_dir; making docs/ and html/ siblings under someli-doc/ is the cleanest workaround.
.pages files (under docs/, audit/, onboard/, and each module directory) — drive the sidebar nav via the awesome-pages plugin. They control:
Section ordering (e.g. product pairs together, snapshots last, _meta last).
Section titles when auto-titling from a directory name would produce something ugly (e.g. Someli-admin-api instead of "Someli admin api").
Edit these to refine the nav without touching the markdown source.
html/ — generated output. Regenerate any time by re-running mkdocs build. Safe to delete — it's not source.

Live-preview while editing¶

cd someli-doc
mkdocs serve     # http://localhost:8000, auto-rebuild on save

Convention¶

Internal links between docs use …/README.md (rather than a bare folder URL like …/) so they work both on GitHub and in the mkdocs HTML output.

Browser note for `file://`¶

Material's client-side search uses fetch() to load the search index. Some browsers block fetch() over file://:

Firefox — works out of the box.
Chrome / Edge — blocks by default; either launch with --allow-file-access-from-files, or just use Firefox for offline reading, or run mkdocs serve for a local web server (http://localhost:8000).

Navigation, code-copy, dark mode, and everything else work in all browsers over file://. Only search is affected.

someli-doc/ — Someli platform documentation¶