README.md

LaraFly Documentation

Everything you need to build production-grade applications with LaraFly — Spring Boot's cohesion, native to Laravel 13.

---

Getting Started

Guide	Description
Introduction	What LaraFly is, the pitch, and a map of the docs
Installation	Requirements, composer create-project firefly/skeleton, and manual install
Getting Started	Boot the firefly/skeleton template, write your first #[RestController]/#[Service], run firefly:cache
Architecture	The hexagonal design, the boot pipeline, and how the Deptrac layers fit together
Tutorial	A hand-built, 12-step walkthrough — from composer create-project to a #[Repository]/#[Valid]/CQRS/#[EventListener] feature slice
Lumen Sample	A runnable digital-wallet & ledger sample exercising #[Transactional], CQRS, domain events over EDA, method security, and a REST layer with RFC-7807 problem-details

---

Module Guides

Every module guide lives under modules/, grouped below the same way as the mkdocs.yml navigation.

Foundation

Guide	Description
Error Handling	firefly/kernel's product-agnostic exception hierarchy and HTTP status mapping
Dependency Injection	firefly/container — attributes, component scan → compiled manifest, container resolution
Configuration	firefly/config — profiles, typed config accessor, #[ConfigProperties], #[Value]
Application Context	firefly/context — the FireflyKernel boot pipeline, conditions, lifecycle callbacks
Auto-Configuration & Starters	firefly/autoconfigure — install a package, get sensible defaults, your own beans win
Validation	firefly/validation — the validate() primitive and financial-domain rules

Web & API

Guide	Description
Web Layer	firefly/web — #[RestController] routing, parameter binding, RFC-7807 error rendering
Web Filters	An ordered WebFilter chain bridged onto Laravel's own middleware pipeline

Resilience & Scheduling

Guide	Description
Resilience	firefly/resilience — Retry, CircuitBreaker, RateLimiter, Bulkhead, TimeLimiter, Fallback
Scheduling	firefly/scheduling — #[Scheduled] on Laravel's own scheduler, with distributed-lock guard

Data & Domain

Guide	Description
Domain (DDD)	firefly/domain — Entity, ValueObject, AggregateRoot, DomainEvent; zero reflection
Data & Repositories	firefly/data — CRUD/paging ports, derived queries, #[Query], Specifications
Relational Data	EloquentRepository — the Eloquent-backed base every repository extends
Transactions	#[Transactional] — declarative transaction demarcation over manual DB::beginTransaction()

Eventing & Messaging

Guide	Description
Event-Driven Architecture	firefly/eda — broker-backed EventPublisher, envelopes, retry/DLQ, in-memory + queue adapters
EDA Brokers	Real broker adapters behind the EventPublisher port — RabbitMQ, Postgres LISTEN/NOTIFY, Kafka
Messaging	firefly/messaging — the lower-level raw-bytes MessageBrokerPort, #[MessageListener]

CQRS

Guide	Description
CQRS (Command/Query)	firefly/cqrs — the CommandBus/QueryBus mediator and the domain→integration-event bridge

Security

Guide	Description
Security	firefly/security — Spring-Security-6-shaped principal model, authN, deny-by-default authZ

Operations

Guide	Description
Actuator	firefly/actuator — health/info/beans endpoints, the Spring-Boot-Actuator analogue
Observability	firefly/observability — the MeterRegistry, Prometheus/Micrometer-JSON exposition, CQRS metrics

Testing

Guide	Description
Testing	firefly/testing — the boot harness, recording doubles, web/data test-slice builders
Integration Testing	Opt-in tests against real backends (Postgres, Kafka), excluded from the default gate

Tooling

Guide	Description
Installer	firefly/installer — the firefly new global scaffolding tool, zero runtime dependencies

---

Reference

Document	Description
CLI Reference	firefly/cli — firefly:cache, firefly:about/:routes/:health/:metrics, make:firefly-*
Laravel Comparison	Side-by-side concept mapping for developers coming from plain Laravel
Versioning	CalVer (YY.MM.Patch), no version field, how Packagist derives releases from tags
Contributing	Monorepo layout, local setup, conventions, how to add a package
Publishing	The release/split runbook — one CalVer tag, 26 shippable units

---

Quick Links

• New to LaraFly? Start with Installation, then Getting Started.
• Coming from plain Laravel? Read the Laravel Comparison.
• Want to see it running end-to-end? Explore the Lumen Sample — a full digital-wallet vertical slice.
• Building a web service? See the Web Layer Guide and Web Filters.
• Understanding the data layer? Start with Data & Repositories, then Relational Data and Transactions.
• Need messaging or events? See Event-Driven Architecture, EDA Brokers, and Messaging.
• Writing commands/queries? See CQRS.
• Securing an app? See Security.
• Shipping to production? See Actuator, Observability, and Resilience.
• Writing tests? See Testing and Integration Testing.
• Releasing a version? See Versioning and Publishing, and check the CHANGELOG.md at the repo root.
• Want to contribute? See Contributing.

---

The guided, book-style LaraFly by Example book — 13 chapters plus appendices, bilingual (English + Spanish), rendered to PDF + EPUB — is available now, alongside the step-by-step Tutorial.

Apache-2.0 © Firefly Software Solutions Inc.