lehsqa/robyn-config-backend-best-practices

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 seven 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
• add observability stack with robyn-config monitoring
• 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
   • monitoring stack setup
   • 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: add observability with robyn-config monitoring

1. Ensure target project is a robyn-config project by checking [tool.robyn-config].
2. Run command:

robyn-config monitoring <project-path>

3. Verify generated artifacts:
   • docker-compose.monitoring.yml at project root.
   • compose/monitoring/alloy/config.alloy — Docker log discovery + Prometheus scrape with job_name = "app".
   • compose/monitoring/prometheus/prometheus.yml — minimal Prometheus config.
   • compose/monitoring/grafana/datasources/loki.yaml and prometheus.yaml — provisioned datasources with fixed UIDs (uid: loki, uid: prometheus).
   • compose/monitoring/grafana/provisioning/dashboards.yaml — dashboard provisioning config.
   • compose/monitoring/grafana/dashboards/logs.json — Loki logs dashboard with search bar.
   • compose/monitoring/grafana/dashboards/metrics.json — Prometheus metrics dashboard.
   • metrics.py injected into the presentation layer and registered as GET /metrics.
4. Verify prometheus-client was installed (or added to pyproject.toml dependencies as fallback).
5. Start the observability stack alongside the app:

docker compose up -d
docker compose -f docker-compose.monitoring.yml up -d

6. Validate:
   • http://localhost:8000/metrics returns Prometheus text output.
   • Grafana at http://localhost:3000 loads both dashboards without errors.
   • Logs panel shows data within 30 seconds of app activity.
   • Metrics panel shows data within one scrape interval (15 s).

Workflow E: 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 F: 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 G: 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/structural-rules.md
  • MANDATORY — structural rules for DDD/MVC code, file paths, naming conventions, and anti-patterns. Load BEFORE touching any generated code.
• references/robyn-config-src-analysis.md
  • Use for robyn-config internals and generation/injection behavior, including the monitoring command.
• 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, including monitoring stack setup and validation.
• 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.