Architecture

Flashboard is being built as a modular monolith packaged as a single Composer library. This keeps installation simple while preserving strong internal boundaries between public contracts, core runtime logic, UI payloads, and Laravel-specific integration.

Main layers

• Contracts: stable public contracts and builder interfaces
• Core: package runtime and business-neutral orchestration
• UI: rendering-oriented payloads and view-layer structures
• Integration/Laravel: service provider, routing, auth, persistence, discovery, and HTTP bridge
• Support: shared utilities that should not leak framework-specific behavior

Dependency rules

• Contracts may be referenced by every other module
• Core may depend on Contracts and Support
• UI may depend on Contracts and normalized Core output
• Integration/Laravel may depend on Contracts, Core, UI, and Laravel APIs
• host applications should plug in business logic through contracts and configuration, not by editing package internals

Key principles

1. Keep the public API declarative and split by concern.
2. Keep typed schema nodes package-owned and normalized into deterministic payloads.
3. Prefer simple $form->schema([...]) authoring for ordinary CRUD screens.
4. Preserve escape hatches for advanced workflows and domain-specific behavior.
5. Keep business logic in the host application, not inside the reusable package.

Intended folder map

src/
├── Contracts/
├── Core/
├── Integration/
│   └── Laravel/
├── Support/
└── UI/

Why this matters

The package has to do two things at once:

• expose a stable public surface that host applications can depend on
• evolve internal runtime behavior quickly during beta

Strong layering makes that balance much easier. Public contracts can stay deliberate, while internal runtime pieces continue to change behind them.