SDH Engineering Standards
We are a Software Development House building production systems for clients. Quality,
maintainability, and security are non-negotiable. Prefer proven community libraries over
custom code.
Tech Stack
| Layer |
Technology |
Notes |
| Backend |
Ruby on Rails |
API-only, shared by all frontends |
| Backend (Python) |
FastAPI (default) or Django + DRF |
AI/ML serving, data pipelines; Django for admin-heavy CRUD |
| AI/ML |
PyTorch, scikit-learn, MLflow |
Served via FastAPI; pgvector for embeddings |
| View Layer |
Phlex (phlex-rails + class_variants) |
OO Ruby views, Atomic Design |
| Serialization |
Panko Serializer |
High-performance JSON (never to_json) |
| Database |
PostgreSQL + PostGIS |
Geospatial relational DB |
| Mobile |
React Native |
Zustand, TanStack Query, Centrifugo, MMKV |
| Web (SPA) |
ReactJS + Vite |
React Router, Tailwind, Framer Motion, ApexCharts |
| Web (SSR) |
Next.js (App Router) |
Server Components, server actions, ISR/SSG |
| State / Data |
Zustand (client) · TanStack Query (server) |
Never store server data in Zustand |
| Real-time |
Centrifugo |
WebSocket channels |
| Cache / Queues |
Redis |
Rails cache + Sidekiq |
| Cloud |
AWS (primary), GCP, Vercel (Next.js) |
ECS Fargate, RDS, ElastiCache, S3, CloudFront |
| Infra |
Terraform + Docker Compose |
All infra as code |
Library preferences
- Auth:
devise + devise-jwt · Authz: pundit · Pagination: pagy · Search: pg_search
- Geospatial:
rgeo, geocoder · HTTP: faraday (Rails), axios (JS)
- Forms:
react-hook-form + zod · Navigation: @react-navigation/native
- Storage:
react-native-mmkv · Images: react-native-fast-image
- Web styling:
tailwindcss + clsx + tailwind-merge · Animations: framer-motion · Charts: react-apexcharts
- Web testing:
vitest + @testing-library/react + msw
- Python:
uv + ruff + mypy · pydantic v2 · httpx · celery (Redis) · SQLAlchemy 2.0 + Alembic (FastAPI) / Django ORM · pytest
- Python AI/ML:
mlflow · pandera · onnxruntime · pgvector · anthropic SDK
Non-negotiables (summary)
- Code: SOLID, DRY, KISS. Functions ≤30 lines, files ≤300 (≤200 for Rails models and UI components). Meaningful names, no magic numbers.
- Architecture: Controllers → Services → Models (Rails); Screens/Pages → Hooks → API Client (frontends). Depend on abstractions.
- Security: OWASP Top 10; parameterized queries only; validate input at boundaries; never commit secrets.
- Testing: AAA pattern;
should [behavior] when [condition]; 80% business-logic coverage.
- Git: Conventional Commits; feature branches; squash-merge; no direct pushes to protected branches.
Where the detail lives
Detailed conventions ship as std-* skills scoped by file path (wrapper-directory
agnostic — Rails works under backend/, api/, or repo root; a Vite app under web/,
frontend/, or root):
- Backend:
std-rails-conventions, std-phlex-conventions, std-api-design, std-database, std-monitoring, std-error-handling
- Python:
std-python, std-fastapi, std-django, std-python-ai-ml, std-python-performance
- Frontend:
std-react-native, std-reactjs, std-nextjs, std-accessibility, std-i18n, std-design-system
- Cross-cutting:
std-code-standards, std-security, std-testing, std-clean-architecture, std-git-workflow, std-infrastructure, std-terraform-conventions, std-agent-teams
Specialized tasks route to the bundled agents (e.g. code-reviewer, security-auditor,
rails-architect, architecture-advisor, incident-responder) and the slash-command skills.
1---2name: sdh-engineering-standards3description: Core engineering standards and tech stack for a Software Development House — Rails + Phlex backend, Python (FastAPI/Django) for AI/ML and data services, React Native, ReactJS (Vite), Next.js, PostgreSQL/PostGIS, Redis/Sidekiq, Terraform on AWS/Vercel. Use whenever writing, reviewing, planning, or scaffolding code in this stack, choosing a library, or setting up a project. Detailed per-area conventions live in the std-* skills (each scoped by file path — load the one that fits the task); specialized work routes to the agents.4---56# SDH Engineering Standards78We are a Software Development House building production systems for clients. Quality,9maintainability, and security are non-negotiable. Prefer proven community libraries over10custom code.1112## Tech Stack1314| Layer | Technology | Notes |15|-------|-----------|-------|16| Backend | Ruby on Rails | API-only, shared by all frontends |17| Backend (Python) | FastAPI (default) or Django + DRF | AI/ML serving, data pipelines; Django for admin-heavy CRUD |18| AI/ML | PyTorch, scikit-learn, MLflow | Served via FastAPI; `pgvector` for embeddings |19| View Layer | Phlex (`phlex-rails` + `class_variants`) | OO Ruby views, Atomic Design |20| Serialization | Panko Serializer | High-performance JSON (never `to_json`) |21| Database | PostgreSQL + PostGIS | Geospatial relational DB |22| Mobile | React Native | Zustand, TanStack Query, Centrifugo, MMKV |23| Web (SPA) | ReactJS + Vite | React Router, Tailwind, Framer Motion, ApexCharts |24| Web (SSR) | Next.js (App Router) | Server Components, server actions, ISR/SSG |25| State / Data | Zustand (client) · TanStack Query (server) | Never store server data in Zustand |26| Real-time | Centrifugo | WebSocket channels |27| Cache / Queues | Redis | Rails cache + Sidekiq |28| Cloud | AWS (primary), GCP, Vercel (Next.js) | ECS Fargate, RDS, ElastiCache, S3, CloudFront |29| Infra | Terraform + Docker Compose | All infra as code |3031### Library preferences32- Auth: `devise` + `devise-jwt` · Authz: `pundit` · Pagination: `pagy` · Search: `pg_search`33- Geospatial: `rgeo`, `geocoder` · HTTP: `faraday` (Rails), `axios` (JS)34- Forms: `react-hook-form` + `zod` · Navigation: `@react-navigation/native`35- Storage: `react-native-mmkv` · Images: `react-native-fast-image`36- Web styling: `tailwindcss` + `clsx` + `tailwind-merge` · Animations: `framer-motion` · Charts: `react-apexcharts`37- Web testing: `vitest` + `@testing-library/react` + `msw`38- Python: `uv` + `ruff` + `mypy` · `pydantic` v2 · `httpx` · `celery` (Redis) · SQLAlchemy 2.0 + Alembic (FastAPI) / Django ORM · `pytest`39- Python AI/ML: `mlflow` · `pandera` · `onnxruntime` · `pgvector` · `anthropic` SDK4041## Non-negotiables (summary)4243- **Code**: SOLID, DRY, KISS. Functions ≤30 lines, files ≤300 (≤200 for Rails models and UI components). Meaningful names, no magic numbers.44- **Architecture**: Controllers → Services → Models (Rails); Screens/Pages → Hooks → API Client (frontends). Depend on abstractions.45- **Security**: OWASP Top 10; parameterized queries only; validate input at boundaries; never commit secrets.46- **Testing**: AAA pattern; `should [behavior] when [condition]`; 80% business-logic coverage.47- **Git**: Conventional Commits; feature branches; squash-merge; no direct pushes to protected branches.4849## Where the detail lives5051Detailed conventions ship as `std-*` skills scoped by file path (wrapper-directory52agnostic — Rails works under `backend/`, `api/`, or repo root; a Vite app under `web/`,53`frontend/`, or root):5455- Backend: `std-rails-conventions`, `std-phlex-conventions`, `std-api-design`, `std-database`, `std-monitoring`, `std-error-handling`56- Python: `std-python`, `std-fastapi`, `std-django`, `std-python-ai-ml`, `std-python-performance`57- Frontend: `std-react-native`, `std-reactjs`, `std-nextjs`, `std-accessibility`, `std-i18n`, `std-design-system`58- Cross-cutting: `std-code-standards`, `std-security`, `std-testing`, `std-clean-architecture`, `std-git-workflow`, `std-infrastructure`, `std-terraform-conventions`, `std-agent-teams`5960Specialized tasks route to the bundled agents (e.g. `code-reviewer`, `security-auditor`,61`rails-architect`, `architecture-advisor`, `incident-responder`) and the slash-command skills.
Kaakati