{"id":"0b107dd0-b649-48c7-9269-a92b55e95703","shortId":"fBV3YB","kind":"skill","title":"Backend Dev Guidelines","tagline":"Antigravity Awesome Skills skill by Sickn33","description":"# Backend Development Guidelines\n\n**(Node.js · Express · TypeScript · Microservices)**\n\nYou are a **senior backend engineer** operating production-grade services under strict architectural and reliability constraints.\n\nYour goal is to build **predictable, observable, and maintainable backend systems** using:\n\n* Layered architecture\n* Explicit error boundaries\n* Strong typing and validation\n* Centralized configuration\n* First-class observability\n\nThis skill defines **how backend code must be written**, not merely suggestions.\n\n---\n\n## 1. Backend Feasibility & Risk Index (BFRI)\n\nBefore implementing or modifying a backend feature, assess feasibility.\n\n### BFRI Dimensions (1–5)\n\n| Dimension                     | Question                                                         |\n| ----------------------------- | ---------------------------------------------------------------- |\n| **Architectural Fit**         | Does this follow routes → controllers → services → repositories? |\n| **Business Logic Complexity** | How complex is the domain logic?                                 |\n| **Data Risk**                 | Does this affect critical data paths or transactions?            |\n| **Operational Risk**          | Does this impact auth, billing, messaging, or infra?             |\n| **Testability**               | Can this be reliably unit + integration tested?                  |\n\n### Score Formula\n\n```\nBFRI = (Architectural Fit + Testability) − (Complexity + Data Risk + Operational Risk)\n```\n\n**Range:** `-10 → +10`\n\n### Interpretation\n\n| BFRI     | Meaning   | Action                 |\n| -------- | --------- | ---------------------- |\n| **6–10** | Safe      | Proceed                |\n| **3–5**  | Moderate  | Add tests + monitoring |\n| **0–2**  | Risky     | Refactor or isolate    |\n| **< 0**  | Dangerous | Redesign before coding |\n\n---\n\n## When to Use\nAutomatically applies when working on:\n\n* Routes, controllers, services, repositories\n* Express middleware\n* Prisma database access\n* Zod validation\n* Sentry error tracking\n* Configuration management\n* Backend refactors or migrations\n\n---\n\n## 3. Core Architecture Doctrine (Non-Negotiable)\n\n### 1. Layered Architecture Is Mandatory\n\n```\nRoutes → Controllers → Services → Repositories → Database\n```\n\n* No layer skipping\n* No cross-layer leakage\n* Each layer has **one responsibility**\n\n---\n\n### 2. Routes Only Route\n\n```ts\n// ❌ NEVER\nrouter.post('/create', async (req, res) => {\n  await prisma.user.create(...);\n});\n\n// ✅ ALWAYS\nrouter.post('/create', (req, res) =>\n  userController.create(req, res)\n);\n```\n\nRoutes must contain **zero business logic**.\n\n---\n\n### 3. Controllers Coordinate, Services Decide\n\n* Controllers:\n\n  * Parse request\n  * Call services\n  * Handle response formatting\n  * Handle errors via BaseController\n\n* Services:\n\n  * Contain business rules\n  * Are framework-agnostic\n  * Use DI\n  * Are unit-testable\n\n---\n\n### 4. All Controllers Extend `BaseController`\n\n```ts\nexport class UserController extends BaseController {\n  async getUser(req: Request, res: Response): Promise<void> {\n    try {\n      const user = await this.userService.getById(req.params.id);\n      this.handleSuccess(res, user);\n    } catch (error) {\n      this.handleError(error, res, 'getUser');\n    }\n  }\n}\n```\n\nNo raw `res.json` calls outside BaseController helpers.\n\n---\n\n### 5. All Errors Go to Sentry\n\n```ts\ncatch (error) {\n  Sentry.captureException(error);\n  throw error;\n}\n```\n\n❌ `console.log`\n❌ silent failures\n❌ swallowed errors\n\n---\n\n### 6. unifiedConfig Is the Only Config Source\n\n```ts\n// ❌ NEVER\nprocess.env.JWT_SECRET;\n\n// ✅ ALWAYS\nimport { config } from '@/config/unifiedConfig';\nconfig.auth.jwtSecret;\n```\n\n---\n\n### 7. Validate All External Input with Zod\n\n* Request bodies\n* Query params\n* Route params\n* Webhook payloads\n\n```ts\nconst schema = z.object({\n  email: z.string().email(),\n});\n\nconst input = schema.parse(req.body);\n```\n\nNo validation = bug.\n\n---\n\n## 4. Directory Structure (Canonical)\n\n```\nsrc/\n├── config/              # unifiedConfig\n├── controllers/         # BaseController + controllers\n├── services/            # Business logic\n├── repositories/        # Prisma access\n├── routes/              # Express routes\n├── middleware/          # Auth, validation, errors\n├── validators/          # Zod schemas\n├── types/               # Shared types\n├── utils/               # Helpers\n├── tests/               # Unit + integration tests\n├── instrument.ts        # Sentry (FIRST IMPORT)\n├── app.ts               # Express app\n└── server.ts            # HTTP server\n```\n\n---\n\n## 5. Naming Conventions (Strict)\n\n| Layer      | Convention                |\n| ---------- | ------------------------- |\n| Controller | `PascalCaseController.ts` |\n| Service    | `camelCaseService.ts`     |\n| Repository | `PascalCaseRepository.ts` |\n| Routes     | `camelCaseRoutes.ts`      |\n| Validators | `camelCase.schema.ts`     |\n\n---\n\n## 6. Dependency Injection Rules\n\n* Services receive dependencies via constructor\n* No importing repositories directly inside controllers\n* Enables mocking and testing\n\n```ts\nexport class UserService {\n  constructor(\n    private readonly userRepository: UserRepository\n  ) {}\n}\n```\n\n---\n\n## 7. Prisma & Repository Rules\n\n* Prisma client **never used directly in controllers**\n* Repositories:\n\n  * Encapsulate queries\n  * Handle transactions\n  * Expose intent-based methods\n\n```ts\nawait userRepository.findActiveUsers();\n```\n\n---\n\n## 8. Async & Error Handling\n\n### asyncErrorWrapper Required\n\nAll async route handlers must be wrapped.\n\n```ts\nrouter.get(\n  '/users',\n  asyncErrorWrapper((req, res) =>\n    controller.list(req, res)\n  )\n);\n```\n\nNo unhandled promise rejections.\n\n---\n\n## 9. Observability & Monitoring\n\n### Required\n\n* Sentry error tracking\n* Sentry performance tracing\n* Structured logs (where applicable)\n\nEvery critical path must be observable.\n\n---\n\n## 10. Testing Discipline\n\n### Required Tests\n\n* **Unit tests** for services\n* **Integration tests** for routes\n* **Repository tests** for complex queries\n\n```ts\ndescribe('UserService', () => {\n  it('creates a user', async () => {\n    expect(user).toBeDefined();\n  });\n});\n```\n\nNo tests → no merge.\n\n---\n\n## 11. Anti-Patterns (Immediate Rejection)\n\n❌ Business logic in routes\n❌ Skipping service layer\n❌ Direct Prisma in controllers\n❌ Missing validation\n❌ process.env usage\n❌ console.log instead of Sentry\n❌ Untested business logic\n\n---\n\n## 12. Integration With Other Skills\n\n* **frontend-dev-guidelines** → API contract alignment\n* **error-tracking** → Sentry standards\n* **database-verification** → Schema correctness\n* **analytics-tracking** → Event pipelines\n* **skill-developer** → Skill governance\n\n---\n\n## 13. Operator Validation Checklist\n\nBefore finalizing backend work:\n\n* [ ] BFRI ≥ 3\n* [ ] Layered architecture respected\n* [ ] Input validated\n* [ ] Errors captured in Sentry\n* [ ] unifiedConfig used\n* [ ] Tests written\n* [ ] No anti-patterns present\n\n---\n\n## 14. Skill Status\n\n**Status:** Stable · Enforceable · Production-grade\n**Intended Use:** Long-lived Node.js microservices with real traffic and real risk\n---\n\n## When to Use\nThis skill is applicable to execute the workflow or actions described in the overview.\n\n## Limitations\n- Use this skill only when the task clearly matches the scope described above.\n- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.\n- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.","tags":["backend","dev","guidelines","antigravity","awesome","skills","sickn33"],"capabilities":["skill","source-sickn33","category-antigravity-awesome-skills"],"categories":["antigravity-awesome-skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/sickn33/antigravity-awesome-skills/backend-dev-guidelines","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"install_from":"skills.sh"}},"qualityScore":"0.300","qualityRationale":"deterministic score 0.30 from registry signals: · indexed on skills.sh · published under sickn33/antigravity-awesome-skills","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill:v1","enrichmentVersion":1,"enrichedAt":"2026-04-25T11:40:45.037Z","embedding":null,"createdAt":"2026-04-18T20:33:35.908Z","updatedAt":"2026-04-25T11:40:45.037Z","lastSeenAt":"2026-04-25T11:40:45.037Z","tsv":"'+10':153 '-10':152 '/config/unifiedconfig':368 '/create':244,252 '/users':527 '0':168,174 '1':73,90,214 '10':159,558 '11':591 '12':619 '13':651 '14':679 '2':169,237 '3':162,207,264,660 '4':295,399 '5':91,163,335,444 '6':158,353,460 '7':370,488 '8':512 '9':538 'access':195,414 'action':157,713 'add':165 'affect':116 'agnost':288 'align':630 'alway':250,364 'analyt':642 'analytics-track':641 'anti':593,676 'anti-pattern':592,675 'antigrav':4 'api':628 'app':440 'app.ts':438 'appli':183 'applic':551,707 'architectur':30,47,94,143,209,216,662 'ask':751 'assess':86 'async':245,306,513,519,583 'asyncerrorwrapp':516,528 'auth':127,419 'automat':182 'await':248,316,510 'awesom':5 'backend':1,10,21,43,65,74,84,203,657 'base':507 'basecontrol':280,299,305,333,407 'bfri':78,88,142,155,659 'bill':128 'bodi':378 'boundari':50,759 'bug':398 'build':38 'busi':103,262,283,410,597,617 'call':272,331 'camelcase.schema.ts':459 'camelcaseroutes.ts':457 'camelcaseservice.ts':453 'canon':402 'captur':667 'catch':322,342 'category-antigravity-awesome-skills' 'central':55 'checklist':654 'clarif':753 'class':59,302,481 'clear':726 'client':493 'code':66,178 'complex':105,107,146,574 'config':358,366,404 'config.auth.jwtsecret':369 'configur':56,201 'console.log':348,612 'const':314,386,392 'constraint':33 'constructor':468,483 'contain':260,282 'contract':629 'control':100,188,220,265,269,297,406,408,450,474,498,607 'controller.list':531 'convent':446,449 'coordin':266 'core':208 'correct':640 'creat':580 'criteria':762 'critic':117,553 'cross':229 'cross-lay':228 'danger':175 'data':112,118,147 'databas':194,223,637 'database-verif':636 'decid':268 'defin':63 'depend':461,466 'describ':577,714,730 'dev':2,626 'develop':11,648 'di':290 'dimens':89,92 'direct':472,496,604 'directori':400 'disciplin':560 'doctrin':210 'domain':110 'email':389,391 'enabl':475 'encapsul':500 'enforc':684 'engin':22 'environ':742 'environment-specif':741 'error':49,199,278,323,325,337,343,345,347,352,421,514,543,632,666 'error-track':631 'event':644 'everi':552 'execut':709 'expect':584 'expert':747 'explicit':48 'export':301,480 'expos':504 'express':14,191,416,439 'extend':298,304 'extern':373 'failur':350 'feasibl':75,87 'featur':85 'final':656 'first':58,436 'first-class':57 'fit':95,144 'follow':98 'format':276 'formula':141 'framework':287 'framework-agnost':286 'frontend':625 'frontend-dev-guidelin':624 'getus':307,327 'go':338 'goal':35 'govern':650 'grade':26,687 'guidelin':3,12,627 'handl':274,277,502,515 'handler':521 'helper':334,429 'http':442 'immedi':595 'impact':126 'implement':80 'import':365,437,470 'index':77 'infra':131 'inject':462 'input':374,393,664,756 'insid':473 'instead':613 'instrument.ts':434 'integr':138,432,567,620 'intend':688 'intent':506 'intent-bas':505 'interpret':154 'isol':173 'layer':46,215,225,230,233,448,603,661 'leakag':231 'limit':718 'live':692 'log':549 'logic':104,111,263,411,598,618 'long':691 'long-liv':690 'maintain':42 'manag':202 'mandatori':218 'match':727 'mean':156 'mere':71 'merg':590 'messag':129 'method':508 'microservic':16,694 'middlewar':192,418 'migrat':206 'miss':608,764 'mock':476 'moder':164 'modifi':82 'monitor':167,540 'must':67,259,522,555 'name':445 'negoti':213 'never':242,361,494 'node.js':13,693 'non':212 'non-negoti':211 'observ':40,60,539,557 'one':235 'oper':23,122,149,652 'output':736 'outsid':332 'overview':717 'param':380,382 'pars':270 'pascalcasecontroller.ts':451 'pascalcaserepository.ts':455 'path':119,554 'pattern':594,677 'payload':384 'perform':546 'permiss':757 'pipelin':645 'predict':39 'present':678 'prisma':193,413,489,492,605 'prisma.user.create':249 'privat':484 'proceed':161 'process.env':610 'process.env.jwt':362 'product':25,686 'production-grad':24,685 'promis':312,536 'queri':379,501,575 'question':93 'rang':151 'raw':329 'readon':485 'real':696,699 'receiv':465 'redesign':176 'refactor':171,204 'reject':537,596 'reliabl':32,136 'repositori':102,190,222,412,454,471,490,499,571 'req':246,253,256,308,529,532 'req.body':395 'req.params.id':318 'request':271,309,377 'requir':517,541,561,755 'res':247,254,257,310,320,326,530,533 'res.json':330 'respect':663 'respons':236,275,311 'review':748 'risk':76,113,123,148,150,700 'riski':170 'rout':99,187,219,238,240,258,381,415,417,456,520,570,600 'router.get':526 'router.post':243,251 'rule':284,463,491 'safe':160 'safeti':758 'schema':387,424,639 'schema.parse':394 'scope':729 'score':140 'secret':363 'senior':20 'sentri':198,340,435,542,545,615,634,669 'sentry.captureexception':344 'server':443 'server.ts':441 'servic':27,101,189,221,267,273,281,409,452,464,566,602 'share':426 'sickn33':9 'silent':349 'skill':6,7,62,623,647,649,680,705,721 'skill-develop':646 'skip':226,601 'sourc':359 'source-sickn33' 'specif':743 'src':403 'stabl':683 'standard':635 'status':681,682 'stop':749 'strict':29,447 'strong':51 'structur':401,548 'substitut':739 'success':761 'suggest':72 'swallow':351 'system':44 'task':725 'test':139,166,430,433,478,559,562,564,568,572,588,672,745 'testabl':132,145,294 'this.handleerror':324 'this.handlesuccess':319 'this.userservice.getbyid':317 'throw':346 'tobedefin':586 'trace':547 'track':200,544,633,643 'traffic':697 'transact':121,503 'treat':734 'tri':313 'ts':241,300,341,360,385,479,509,525,576 'type':52,425,427 'typescript':15 'unhandl':535 'unifiedconfig':354,405,670 'unit':137,293,431,563 'unit-test':292 'untest':616 'usag':611 'use':45,181,289,495,671,689,703,719 'user':315,321,582,585 'usercontrol':303 'usercontroller.create':255 'userrepositori':486,487 'userrepository.findactiveusers':511 'userservic':482,578 'util':428 'valid':54,197,371,397,420,422,458,609,653,665,744 'verif':638 'via':279,467 'webhook':383 'work':185,658 'workflow':711 'wrap':524 'written':69,673 'z.object':388 'z.string':390 'zero':261 'zod':196,376,423","prices":[{"id":"f3d1e0ba-d679-47fa-9ce4-dbcde422c20b","listingId":"0b107dd0-b649-48c7-9269-a92b55e95703","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"sickn33","category":"antigravity-awesome-skills","install_from":"skills.sh"},"createdAt":"2026-04-18T20:33:35.908Z"}],"sources":[{"listingId":"0b107dd0-b649-48c7-9269-a92b55e95703","source":"github","sourceId":"sickn33/antigravity-awesome-skills/backend-dev-guidelines","sourceUrl":"https://github.com/sickn33/antigravity-awesome-skills/tree/main/skills/backend-dev-guidelines","isPrimary":false,"firstSeenAt":"2026-04-18T21:33:18.651Z","lastSeenAt":"2026-04-25T06:50:41.608Z"},{"listingId":"0b107dd0-b649-48c7-9269-a92b55e95703","source":"skills_sh","sourceId":"sickn33/antigravity-awesome-skills/backend-dev-guidelines","sourceUrl":"https://skills.sh/sickn33/antigravity-awesome-skills/backend-dev-guidelines","isPrimary":true,"firstSeenAt":"2026-04-18T20:33:35.908Z","lastSeenAt":"2026-04-25T11:40:45.037Z"}],"details":{"listingId":"0b107dd0-b649-48c7-9269-a92b55e95703","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"sickn33","slug":"backend-dev-guidelines","source":"skills_sh","category":"antigravity-awesome-skills","skills_sh_url":"https://skills.sh/sickn33/antigravity-awesome-skills/backend-dev-guidelines"},"updatedAt":"2026-04-25T11:40:45.037Z"}}