Skip to content

04 — Your first contribution to designer-api

A walkthrough for shipping your first ticket.

1. Pick a small first task

Good first tickets:

  1. Doc fix in ../../audit/designer-api/.
  2. A console.log cleanup from ../../code-inspect/designer-api.md.
  3. Move a hardcoded credential to an env var. The Slack token in teamsnotification.js is a known finding; same for the Unsplash key. Use a .env value instead.
  4. Fix the malformed double CORS header in server.js. Remove the redundant manual Access-Control-Allow-Origin: * and the malformed "Access-Control-Allow-Credentials" : true line. The cors() middleware above already does the right thing.

Avoid for your first PR: any industry-clone job (the change might need to apply to all 30+), anything inside routes/routes.js over 100 lines long, any bot that hits OpenAI for cost reasons (until you have a dev key budget).

2. The edit-run-verify loop

cd ~/src/someli/designer-api

# 1. Branch
git checkout dev
git pull origin dev
git checkout -b fix/first-pr

# 2. Edit a file

# 3. Run
yarn start                          # nodemon — auto-restarts

# 4. Verify
curl -i http://localhost:5003/<endpoint>

There is no /health endpoint to ping; you have to know an endpoint that doesn't require auth (e.g., a static asset or a public read endpoint — see ../../audit/designer-api/API-inventory.md).

3. Entry points to know — a 20-minute reading tour

  1. server.js (70 lines). Read the whole file — the differences from someli-api/server.js are exactly what makes this repo distinct.
  2. conf.js (27 lines). Tiny env-var surface. Notice what's missing compared to someli-api/conf.js.
  3. routes/routes.js — scroll. Find apiRoutes.prototype.init (~line 91). Note that 269 endpoints are all in this file.
  4. helper/index.js (88 lines). Read every line.
  5. One job_*.js of your choice — pick a non-industry-clone like post_approve_job.js. Read cover to cover.
  6. One bot of your choice — pick quotesbot.js or FAQsbot.js. Read it.

After this, you can place 90% of new code in the right file.

4. Reading-around your task

  1. Grep within the repo: 
    grep -n 'mySearchTerm' routes/routes.js helper/index.js
grep -ln 'mySearchTerm' job_*.js *bot.js
  2. Grep across the platform (the DB is shared): 
    cd ~/src/someli
grep -rln 'mySearchTerm' someli-api/ designer-api/ Someli-admin-api/
  3. Open the relevant audit doc:
  4. Jobs → ../../audit/designer-api/jobs-inventory.md
  5. Bots → ../../audit/designer-api/bots-inventory.md
  6. Endpoints → ../../audit/designer-api/API-inventory.md
  7. Content pipeline → ../../audit/designer-api/content-pipeline.md

5. Manual testing

No test suite — same as the rest of the platform.

For an endpoint change:

  1. Happy path via curl or the designer FE pointed at your local backend.
  2. Bad input (wrong types, missing fields).
  3. DB error (stop MySQL, hit the endpoint, see what happens).

For a job change:

  1. Comment out the cron.schedule(...) line so the job doesn't auto-run.
  2. Wrap the handler body and invoke it manually: node -e 'require("./job_X").handler()' (or refactor the file to expose the handler).
  3. Verify the DB and S3 effects.
  4. Restore the cron.schedule(...).

For a bot change: same as a job, but pay attention to OpenAI costs — bots often run in batches.

6. Useful local helpers

Scratch script

// scratch.js (untracked — add to .gitignore)
require('dotenv').config();
const mysql = require('sync-mysql');
const con = new mysql({
  host: process.env.host,
  user: process.env.user,
  password: process.env.password,
  database: process.env.database,
});

const rows = con.query("SELECT * FROM tTemplate LIMIT 5");
console.log(rows);

Talking to the DB

Same as someli-api — use any MySQL client.

7. Opening the PR

git add -p
git commit -m "Fix double CORS header in server.js"
git push -u origin fix/first-pr
# Open PR on github.com/Someli-ai/designer-api → dev

PR description should note:

  • Why the change is needed
  • What changed
  • Manual test plan — there is no CI, so the reviewer needs to know how you verified
  • Whether the change applies to industry-clone jobs (and if so, whether you applied it to all of them)

8. After merge

  • The repo has no in-repo CI/CD — the deploy is run by ops outside the repo. Ask the team how to confirm the dev deploy actually happened.
  • Pull dev locally and clean up your branch.

9. Common first-PR mistakes

Mistake Why it bites Avoid by
Committing your .env Leaks secrets Confirm .gitignore covers it; git status before commit
Editing one industry-clone job and not the others Half the industries get the fix, half don't Decide explicitly: is this industry-specific, or all-clones?
Adding sync-mysql to new code Blocks the event loop Prefer mysql2/promise
Hardcoding a new credential Compound the existing finding Always use env vars
Adding a cron.schedule(...) that fires every minute Spams the shared DB and OpenAI Run it on a sensible interval; test with shorter intervals only locally with a guard
Breaking the malformed CORS header by "fixing" it without testing the FE The FE never sets credentials anyway, but other tooling might Verify with curl -v that the response still has the right headers, then test the designer FE
Forgetting designer-api shares MySQL with someli-api & Someli-admin-api Schema change breaks another repo's job at 2 AM Coordinate schema changes in advance

Next

→ 05-where-to-look.md.