# Blueprint Boilerplate Gap Analysis

Date: 2026-05-12

## Executive Summary

Blueprint already has a strong AI-assisted local-dev foundation: Angular,
NestJS, GraphQL, Prisma, admin/auth basics, tmux-managed Dev Console tooling,
Telegram/operator workflows, and chunk-based delivery standards. The largest
gap is not another framework dependency. The gap is a set of product-grade
conventions that mature ecosystems provide by default: durable auth, policy
authorization, database lifecycle, resource CRUD scaffolding, mail/notification
flow, jobs, auditability, files, and operational health.

Laravel, Rails, Django, and Filament are productive because they define boring
paths for common work. Blueprint should do the same for Angular/Nest/GraphQL,
while keeping AI workflow tooling separate from product boilerplate. The next
work should prioritize small, canonical foundations and generators over broad
"platform" features.

## Current Blueprint Strengths

- Monorepo foundation with Yarn workspaces, Angular frontend, NestJS backend,
  GraphQL codegen, and Prisma.
- Auth/admin seed already exists: JWT auth, bcrypt password hashing, user role
  enum, admin/user frontend routes, and bootstrap/reset tooling.
- UI foundations exist: theme shell, navigation, admin area, Dev Console, PWA
  manifest/icons, and local/dev responsive improvements.
- Local-dev AI workflow is unusually advanced: chunks, roles, standards, tmux
  runtime sessions, Telegram transport, operator questions, Codex I/O bridge,
  trusted operator daemon, and managed dev servers.
- Validation has structure: lint/test/build scripts, workflow scenario tests,
  runtime smoke scripts, and chunk QA expectations.
- Backend has initial common infrastructure: config validation, exception
  filter, logging interceptor, health/smoke endpoint patterns, and GraphQL.

## Major Missing Foundations

The current app is a capable skeleton, but not yet a serious reusable app
starter. The highest-risk missing foundations are:

- Durable account/session model with password reset, email verification, and
  safer token/session defaults.
- Authorization policies/permissions beyond a role enum.
- Database lifecycle conventions: migrations, seeds, factories, fixtures, and
  test reset flow.
- Resource CRUD scaffolding for GraphQL + Angular admin screens.
- Email/notification and background job primitives.
- Audit/activity logging for admin and privileged actions.
- File/media upload handling with security defaults.
- Developer "doctor" and generator tooling that make the happy path repeatable.

## Prioritized Roadmap

### App And Product Boilerplate

| Priority | Item | What It Is | Why It Matters | Analogue | Blueprint Status | Recommended Next Action |
| --- | --- | --- | --- | --- | --- | --- |
| P0 | Durable auth/session foundation | Access/session strategy, refresh or cookie option, password reset, email verification, logout semantics | Real apps need reliable identity and predictable restore across reloads | Laravel starter kits/Fortify, Rails auth generators, Django auth | Partial | Design one canonical auth model and tests before more app features |
| P0 | Authorization policy layer | Permissions, policies/guards, frontend ability checks, role-to-permission mapping | Prevents role checks from scattering through resolvers/components | Laravel policies/gates, Django permissions, Rails Pundit-style convention | Partial | Add backend policy API and frontend ability service |
| P0 | Database lifecycle | Prisma migration policy, seeds, factories, test DB reset, fixture conventions | Mature teams need reproducible local/test environments | Laravel migrations/seeding/factories, Rails migrations/fixtures, Django migrations | Partial | Define seed/test-data standard and baseline scripts |
| P0 | Admin resource CRUD scaffold | List/detail/create/edit patterns, server pagination/filter/sort, validation errors | Most apps start with admin CRUD; conventions avoid bespoke screens | Filament resources, Nova resources, Django admin, Rails scaffold | Partial | Build one canonical resource pattern using users as reference |
| P0 | Validation and error UX | Shared validation shape, GraphQL error mapping, form field errors, toast/error standards | Keeps backend/frontend behavior consistent and debuggable | Laravel form requests, Rails validations, Django forms | Partial | Standardize DTO/input validation and Angular form error mapping |
| P1 | Email and notifications | Templated mail, notification abstraction, dev mailbox/log transport | Password reset, verification, invites, alerts all depend on it | Laravel notifications/mail, Rails Action Mailer, Django email | Lacks | Add dev-only mail sink first, production adapter later |
| P1 | Jobs and scheduler | Queue worker, retries, idempotency, scheduled tasks | Needed for email, imports, AI jobs, reports, cleanup | Laravel queues/scheduler, Rails Active Job, Django/Celery pattern, Nest queues | Lacks | Pick queue strategy and add one background job example |
| P1 | Audit/activity log | Record privileged/admin/user actions and security-sensitive events | Admin and AI-operated apps need traceability | Laravel activity-log ecosystem, Django admin log, Rails auditing gems | Lacks | Add generic audit event model/service with admin viewer later |
| P1 | Settings/preferences | System settings, user preferences, feature flags/local config | Avoids hardcoding product options in env or source | Laravel config + settings packages, Rails credentials/config | Lacks | Start with user preferences and typed system settings |
| P1 | File/media handling | Upload validation, storage abstraction, signed URLs, size/type rules | Almost every app eventually handles files | Laravel filesystem, Rails Active Storage, Django file storage | Lacks | Add storage interface and secure upload policy before UI |
| P2 | Billing/subscriptions | Plans, invoices, Stripe integration | Useful for SaaS, but not every app | Laravel Cashier, SaaS kits | Lacks | Defer until a product requires it |
| P2 | Team/org tenancy | Organizations, memberships, invitations, scoped data | Important for B2B SaaS, risky to retrofit | Laravel Jetstream teams, SaaS boilerplates | Lacks | Decide early per product; do not bake in too soon |
| P2 | API documentation conventions | GraphQL schema docs, operation examples, auth conventions | Helps external consumers and agents | Rails API docs, Nest Swagger for REST, GraphQL schema tooling | Partial | Add GraphQL documentation/report generation |
| P3 | Full CMS/marketing admin | Pages, blocks, rich content | Often overbuilt before product fit | Django CMS, Laravel CMS packages | Lacks | Do not add to core Blueprint yet |

### AI Engineering Workflow And Local Operation

| Priority | Item | What It Is | Why It Matters | Analogue | Blueprint Status | Recommended Next Action |
| --- | --- | --- | --- | --- | --- | --- |
| P0 | Single operator decision model | Human questions only when a fresh human decision is required; either Telegram or local answer wins; explicit user authorization can cover a requested close/commit flow without duplicate prompts | Prevents approval loops and stale Telegram confusion | CI approval gates, ChatOps approval flows | Partial | Add this rule to canonical operator standards and tests |
| P0 | Daemon-only registered actions | Git add/commit, complete chunk, dev-server lifecycle, screenshots, and runtime checks through trusted daemon | Avoids Codex platform escalation and sandbox namespace confusion | Build agents, CI runners, local task daemons | Partial/active | Finish hardening docs/tests so registered actions never fall back silently |
| P0 | Missing-action registry | When Codex needs an action not registered in daemon, record it and ask operator whether to implement, fallback, or stop | Prevents ad hoc shell/platform escalation paths | Internal platform task catalogs | Lacks | Add standard and report format |
| P1 | Codex I/O bridge robustness | Detect prompts, inject answers, avoid duplicate Telegram noise | Makes remote operation genuinely hands-off | Terminal automation/ChatOps bridge | Partial | Continue fixture and live tests, reduce command surface |
| P1 | Runtime doctor | One command checks tmux sessions, daemon, Telegram, ports, Playwright, env, DB | Cuts debugging time for local/dev operator workflow | Laravel `about`, Rails doctor-like scripts, framework diagnostics | Partial | Add `ai/tools/local-dev/doctor.sh` |
| P1 | Workflow scorecard | Machine-readable status for chunks, QA, validation, daemon health | Lets Codex decide next action reliably | CI status dashboards | Partial | Generate compact JSON plus human summary |
| P2 | AI task templates/generators | Generate chunks, QA prompts, resource feature plans | Reduces prompt drift | Rails/Laravel generators adapted to AI workflow | Partial | Add after app scaffolds stabilize |

### Developer Experience

| Priority | Item | What It Is | Why It Matters | Analogue | Blueprint Status | Recommended Next Action |
| --- | --- | --- | --- | --- | --- | --- |
| P0 | Feature/resource generator design | Create Nest module/resolver/service, GraphQL ops, Angular route/table/form/tests | Repetition is the main cost in full-stack CRUD apps | Rails scaffold, Laravel artisan make, Filament resource generator | Lacks | Design generator spec before implementation |
| P0 | Test data and e2e standard | Factories, seeded users, browser auth helpers, deterministic fixtures | Prevents brittle tests and manual setup | Laravel factories, Rails fixtures/factories, Django fixtures | Partial | Add shared fixture/testing conventions |
| P1 | CI baseline | Lint, test, build, codegen/schema drift, chunk checks | Keeps Blueprint reliable outside local dev | GitHub Actions/common SaaS boilerplate CI | Partial/unknown | Add CI after scripts settle |
| P1 | Environment/deployment guide | Local/staging/prod env map, secret handling, migration process | Avoids unsafe production drift | Laravel env docs, Rails credentials/deploy, Django settings | Partial | Write deploy/env standard before production features |
| P1 | Observability baseline | Request IDs, structured logs, health/readiness, error reporting hooks | Serious apps need production debugging | Rails logs, Laravel logging, Nest interceptors | Partial | Add request ID and health/readiness standard |
| P2 | Pre-commit hooks | Optional lint/format/test guardrails | Useful but can slow local iteration | Husky/lint-staged, framework defaults | Lacks | Add only after command speeds are acceptable |
| P2 | Package/template publishing | Initialize new app from Blueprint | Makes Blueprint reusable outside this repo | Rails new, Laravel installer, SaaS kit templates | Lacks | Defer until foundation chunks are complete |

## P0 Recommendations

1. Define the canonical auth/session model, including password reset and email
   verification. The current auth is useful, but not a complete app baseline.
2. Add a policy/permission layer before more admin features grow direct role
   checks.
3. Standardize database lifecycle: migrations, seeds, factories, and test reset.
4. Create one canonical admin CRUD resource pattern with GraphQL pagination,
   filtering, sorting, validation, and Angular form/table conventions.
5. Add a single operator-decision standard update: ask humans only when a fresh
   human decision is required; do not ask duplicate Telegram/git approvals when
   the user already explicitly authorized the flow.
6. Finish daemon-only enforcement for registered actions, with a missing-action
   registry for anything not yet supported by the daemon.
7. Design generator scaffolding after the first resource pattern is stable.

## P1 Recommendations

- Add email/notification infrastructure with a dev mailbox/log transport.
- Add a job/queue/scheduler foundation using a proven library rather than a
  custom queue.
- Add audit/activity logging for auth, admin, and operator-daemon actions.
- Add settings/preferences and feature flag conventions.
- Add storage/upload primitives with strict validation.
- Add a local-dev doctor and compact workflow scorecard.
- Add CI once local validation scripts are stable.

## P2/P3 Later Items

- Billing/subscriptions.
- Team/org tenancy.
- Full CMS/marketing page builder.
- Offline-first PWA caching.
- Multi-provider OAuth/social login.
- Rich plugin marketplace or package publishing.
- Kubernetes/production platform automation.

## Laravel And Scaffold Comparison Notes

Laravel is a strong reference because it separates framework primitives from
optional scaffolds:

- Starter kits provide application auth scaffolding instead of forcing every
  project to rebuild login and registration.
- Fortify offers backend auth actions; Jetstream adds profile, team, session,
  and token-oriented application scaffolding.
- Policies/gates give authorization a named home instead of ad hoc role checks.
- Notifications, queues, scheduler, filesystem, migrations, and seeders make
  common product work feel native.
- Nova and Filament show the value of resource-based admin CRUD.

Rails contributes a different lesson: conventions and generators matter. A
resource scaffold is valuable not because it is perfect, but because it creates
the same files, routes, validations, jobs, mailers, tests, and migrations in a
predictable shape.

Django shows how much leverage an admin, auth, permissions, forms, and
migrations baseline gives a team before product-specific UI exists.

NestJS provides the right primitives for modules, guards, pipes, interceptors,
config, and queues, but it does not impose a complete app scaffold. Blueprint
should define those conventions for this stack.

## What Not To Build Yet

- Do not build a Nova/Filament clone before one excellent resource pattern
  exists.
- Do not add billing until a target product requires billing.
- Do not add teams/multi-tenancy globally until the data model needs it.
- Do not implement a custom queue. Use a proven queue library when jobs become
  necessary.
- Do not add aggressive service-worker caching for local/dev workflows; stale
  UI would harm operator work.
- Do not create a large Telegram command shell. Keep Telegram as an answer
  surface and use daemon actions for execution.
- Do not add broad arbitrary shell execution to the operator daemon.
- Do not overbuild generators before conventions are proven manually once.

## Suggested Next Chunks

1. **Auth/session foundation requirements**
   - Decide access/refresh/cookie strategy, password reset, email verification,
     logout semantics, and production/local defaults.
2. **Authorization policy layer**
   - Add permission registry, backend guard/policy helpers, and frontend ability
     service.
3. **Admin resource scaffold reference**
   - Make users the reference resource for list/detail/create/edit, server
     pagination/filter/sort, GraphQL operations, Angular form error mapping,
     and tests.
4. **Database lifecycle and test data**
   - Define migrations, seeds, factories, deterministic fixtures, and test DB
     reset conventions.
5. **Operator decision and daemon missing-action audit**
   - Canonicalize "ask only when human approval is required", daemon-only
     registered actions, and missing-action reporting.

## Open Questions For Human Review

- Should Blueprint optimize first for internal admin apps, B2B SaaS, or general
  product prototypes? This affects teams, billing, permissions, and CRUD depth.
- Should sessions be browser-cookie based or bearer-token based for the first
  production-ready auth pass?
- Is multi-tenancy a near-term requirement or a later optional module?
- Which queue backend should be preferred for local/dev and production:
  Postgres-backed jobs, Redis/BullMQ, or another adapter?
- Should generated admin CRUD be a CLI generator, an AI chunk template, or both?
- Which deployment target should guide env/deploy conventions first?
- How strict should the operator-daemon registered-action model be for local
  trusted development versus CI-like automation?

## Sources

- [Laravel starter kits](https://laravel.com/docs/starter-kits)
- [Laravel Fortify](https://laravel.com/docs/fortify)
- [Laravel Jetstream](https://jetstream.laravel.com/introduction.html)
- [Laravel authorization](https://laravel.com/docs/authorization)
- [Laravel queues](https://laravel.com/docs/queues)
- [Laravel notifications](https://laravel.com/docs/notifications)
- [Laravel task scheduling](https://laravel.com/docs/scheduling)
- [Laravel migrations](https://laravel.com/docs/migrations)
- [Laravel seeding](https://laravel.com/docs/seeding)
- [Laravel filesystem](https://laravel.com/docs/filesystem)
- [Laravel Cashier billing](https://laravel.com/docs/billing)
- [Filament resources](https://filamentphp.com/docs/3.x/panels/resources/getting-started)
- [Rails guides](https://guides.rubyonrails.org/)
- [Rails Active Job](https://guides.rubyonrails.org/active_job_basics.html)
- [Rails Action Mailer](https://guides.rubyonrails.org/action_mailer_basics.html)
- [Rails Active Storage](https://guides.rubyonrails.org/active_storage_overview.html)
- [Django admin](https://docs.djangoproject.com/en/stable/ref/contrib/admin/)
- [Django authentication](https://docs.djangoproject.com/en/stable/topics/auth/)
- [Django migrations](https://docs.djangoproject.com/en/stable/topics/migrations/)
- [NestJS documentation](https://docs.nestjs.com/)
- [NestJS authentication](https://docs.nestjs.com/security/authentication)
- [NestJS authorization](https://docs.nestjs.com/security/authorization)
- [NestJS queues](https://docs.nestjs.com/techniques/queues)