Robyn Config Backend Best Practices

Overview and intent

Use this skill to work effectively with robyn-config and production-oriented Robyn backend patterns.

This skill is optimized for six task groups:

• scaffold a new service with robyn-config create
• extend an existing service with robyn-config add
• scaffold admin panel with robyn-config adminpanel
• keep local skill installation synchronized with latest robyn-config package releases
• audit and improve architecture and operational readiness
• author high-quality skill files for Robyn engineering work

Do not load every reference file by default. Load only the files required for the current task.

Fast triage workflow

1. Detect project metadata in pyproject.toml:
   • [tool.robyn-config].design (ddd or mvc)
   • [tool.robyn-config].orm (sqlalchemy or tortoise)
   • [tool.robyn-config].package_manager (uv or poetry)
2. Classify requested work:
   • bootstrap
   • extension
   • adminpanel scaffolding
   • package release sync
   • architecture or operations audit
   • skill authoring
3. Select references from the routing table in this file.
4. Produce branch-specific guidance for design, ORM, and package manager.
5. End with a validation checklist and concrete commands.

Workflow A: bootstrap from robyn-config create

1. Select stack options: design, ORM, package manager.
2. Generate service:

robyn-config create <service-name> --design <ddd|mvc> --orm <sqlalchemy|tortoise> --package-manager <uv|poetry> <destination>

3. Confirm output baseline:
   • pyproject.toml contains [tool.robyn-config]
   • src/app layout matches selected design
   • lock file matches package manager (uv.lock or poetry.lock)
4. Execute ORM-specific migration bootstrap before app start.
5. Run lint, type checks, and tests, then report exact failures with file paths.

Workflow B: evolve project with robyn-config add

1. Ensure target project is a robyn-config project by checking [tool.robyn-config].
2. Read optional path overrides under [tool.robyn-config.add].
3. Add module:

robyn-config add <entity-name> <project-path>

4. Verify generated updates:
   • new files in expected layer paths
   • route registration inserted in the right registry file
   • repository exports and tables updated
   • no duplicate symbols or broken imports
5. Regenerate migrations if schema changed.
6. Run checks and confirm command rollback behavior if failures occur.

Workflow C: add admin panel with robyn-config adminpanel

1. Ensure target project is a robyn-config project by checking [tool.robyn-config].
2. Check whether [tool.robyn-config.adminpanel].created = true already exists; if yes, account for update confirmation behavior.
3. Run command:

robyn-config adminpanel [-u <admin-username>] [-p <admin-password>] <project-path>

4. Verify generated behavior:
   • admin module exists for the selected design and is registered in app startup.
   • /admin UI supports dark/light themes.
   • project models are auto-discovered and listed under /admin/models.
   • CRUD flows are available for discovered model tables.
   • admin auth bootstrap is configured for default or provided superadmin credentials.
5. Verify dependencies and metadata updates in pyproject.toml:
   • required dependencies: jinja2, aiosqlite, pandas, openpyxl
   • [tool.robyn-config.adminpanel].created = true
6. Run checks and confirm command rollback behavior if failures occur.

Workflow D: review and improve architecture and ops readiness

1. Validate architecture boundaries for selected design.
2. Validate runtime safety:
   • settings and env overrides
   • auth, session, CORS behavior
   • transaction boundaries and error mapping
3. Validate operations:
   • migration startup order
   • compose and local parity
   • logging and debug posture
4. Prioritize recommendations:
   • P0 correctness and security
   • P1 reliability and consistency
   • P2 maintainability and performance
5. Provide file-targeted, diff-ready changes.

Workflow E: author and update skill files for Robyn engineering

1. Keep SKILL.md concise and procedural.
2. Put deep detail into references/ and load on demand.
3. Write frontmatter with explicit trigger contexts.
4. Reuse rule patterns from react-best-practices where useful.
5. Validate skill structure before delivering:
   • no placeholder markers
   • all referenced files exist
   • no extra docs such as README or changelog inside skill folder

Workflow F: sync skills after a robyn-config package release

1. Run:

./skills/robyn-config-backend-best-practices/scripts/update-if-new-robyn-config.sh

2. Script behavior:
   • checks installed robyn-config version vs latest PyPI version
   • if newer version exists, runs python -m pip install --upgrade robyn-config
   • then runs npx skills update
   • if already up to date, exits without changes

Reference routing table

Open only the file needed for the task:

• references/robyn-config-src-analysis.md
  • Use for robyn-config internals and generation/injection behavior.
• references/robyn-backend-best-practices.md
  • Use for prioritized engineering guidance and review criteria.
• references/robyn-config-workflows.md
  • Use for operator playbooks and command sequences.
• references/architecture-ddd-vs-mvc.md
  • Use for architecture selection and refactor planning.
• references/orm-sqlalchemy-vs-tortoise.md
  • Use for ORM tradeoffs and migration/session behavior.
• references/skill-authoring-patterns.md
  • Use for writing and validating high-quality skill markdown.
• references/react-style-rule-system.md
  • Use for reusable rule-library design patterns and taxonomy.
• scripts/update-if-new-robyn-config.sh
  • Use to check for a newer robyn-config release and update local skills only when needed.

Output requirements

Always:

1. Include concrete executable commands.
2. Include design and ORM branch-specific instructions.
3. Include package-manager-aware instructions (uv and poetry).
4. Include a validation checklist covering structure, behavior, and checks.
5. State assumptions explicitly when repository context is incomplete.