Someli Platform — Developer Documentation¶
This directory contains developer onboarding docs for the Someli platform. They are written for someone who has just been given access to the repo and needs to be productive quickly.
If you only read one document, read 01-local-setup.md.
Reading order¶
The docs build on each other; the suggested order is:
Core onboarding (read top-to-bottom on day one)¶
| # | Document | Read when… |
|---|---|---|
| 01 | Local development setup | First day. You need to get the project running. |
| 02 | Architecture overview | Before touching anything non-trivial. |
| 03 | Auth & session lifecycle | Anything that touches login, accounts, or redirects. |
| 04 | Routing & account scoping | Adding or moving a page; debugging redirects. |
| 05 | State management | Any feature that fetches or mutates data. |
| 06 | Polotno integration | Working on the design editor. |
| 07 | Build & deploy | Diagnosing CI, Docker, or env-var issues. |
| 08 | Third-party integrations | Touching social, billing, AWS, email, AI. |
| 09 | Coding conventions | Before opening a PR. |
| 10 | Troubleshooting & gotchas | When something is silently wrong. |
Domain & reference (read on demand)¶
| # | Document | Read when… |
|---|---|---|
| 11 | Glossary | You don't recognise a term in code or in conversation. |
| 12 | Permissions & roles model | Adding a role-gated feature; debugging "can't access this page" issues. |
| 13 | Post lifecycle state machine | Working on the content planner, post status, or approvals. |
| 14 | API endpoint catalog | "Does an endpoint already exist for X?" |
| 15 | Onboarding flow | Touching any onboarding step page. |
| 16 | Layouts reference | Choosing a layout for a new page. |
| 17 | Helpers & shared utilities | Looking for a formatter, status helper, or avatar/initials utility. |
| 18 | Modal patterns | Adding a modal — check the inventory first. |
| 19 | Feature inventory | "Where does feature X live?" |
| 20 | PR & contribution workflow | Before opening a PR. |
Document scope¶
These docs describe the frontend repo (someli-platform). The backend API is a separate service consumed via process.env.API_URL — its endpoints are referenced here but not documented in this repo. When an endpoint description is needed, ask the backend team or trace the call site.
Conventions used in these docs¶
- File paths are repo-relative unless prefixed with
/. - "Root project" means the Nuxt application at the top of the repo.
- "Polotno editor" means the React sub-project at
polotno-editor/. - "Backend" means the external HTTP API at
process.env.API_URL. - Anything labeled Verify with the team is a documented uncertainty — the doc was written from code reading and the value should be confirmed before relying on it.
Keeping these docs honest¶
Treat these docs as a living artifact. When you change one of the load-bearing files (middleware/redirect.js, middleware/axios.js, middleware/appendUrl.js, store/api.js, nuxt.config.js, Dockerfile, Jenkinsfile, the polotno bundle entry point, helpers/helper.js), check whether the corresponding doc still reads correctly and update it in the same PR. See the table at the bottom of 20-contributing.md for the file-to-doc mapping.