Stackmint

A low-magic PHP framework starter for small SaaS and internal business apps.

Stackmint is the application skeleton. Wayfinder is the reusable core framework behind it. The framework repos are currently private while the public showcase and documentation are being prepared.

Why Stackmint Exists

Modern PHP frameworks are often optimized for broad ecosystems, deep abstraction layers, and large community conventions.

That works well for many teams, but it is not always the right fit for smaller business applications where the priorities are different:

• explicit request flow
• clear file responsibilities
• direct database access when needed
• low magic
• code that is easier for both developers and AI tools to understand

Stackmint exists to make those tradeoffs intentionally.

It is designed for teams building small SaaS products, internal tools, client portals, workflows, dashboards, and other business apps that benefit from predictable structure without a large amount of hidden framework behavior.

What Stackmint Is

Stackmint is the PHP framework skeleton the application is built on.

Wayfinder is the reusable core framework package behind it.

Together they provide a framework shape that emphasizes:

• explicit architecture
• model-first application code
• first-class low-level database access
• optional escalation to query and service patterns
• small, readable building blocks

What Makes It Different

• Explicit request lifecycle
• Model-first architecture by default
• First-class DB access without forcing an ORM
• Optional Query and Service patterns when complexity grows
• Modular application structure
• No queue system by default
• No ORM
• AI-readable conventions and file boundaries

This is not trying to be a general-purpose framework for every kind of PHP application. It is built for a narrower goal: structured business apps with low magic and clear architecture.

Architecture Overview

At the request level, the default application flow is:

HTTP Request -> Router -> Controller -> Model / Query / Service -> Response

At the framework level, the split is:

Stackmint starter -> Wayfinder core

Key principles:

• explicit over implicit
• low magic
• model-first by default
• DB remains available for deliberate low-level control
• optional patterns only when complexity justifies them

Related diagrams:

• Stackmint / Wayfinder Relationship
• Request Lifecycle

Mental Model

Stackmint uses a simple decision ladder:

• Model = entity behavior
• Query = complex read shape
• Service = workflow
• DB = low-level control
• DTO = explicit output shape

In practice that means:

• start with Model for normal application data work
• move to Query when reads become join-heavy, aggregate-heavy, or report-shaped
• move to Service when a feature becomes a multi-step workflow
• use DB when you intentionally want direct query control

Code Shape

Even though the main framework repos are private for now, the framework follows a direct and inspectable application style.

Route Definition

Router::get('/tasks', [TaskController::class, 'index']);

Request Validation

$data = $request->validate([
    'title' => 'required|string|max:255',
    'status' => 'required|string',
]);

Model-First Read

$tasks = Task::where('status', 'open')
    ->latest('updated_at')
    ->take(10)
    ->get();

Query For A Complex Read

$tasks = $taskListQuery->execute($userId, $projectFilter, $statusFilter, $labelFilter, $today);

Service For Workflow Logic

$syncInvoices->handle($account, $payload);

Project Structure

The starter and core are intentionally separated.

stackmint/
  app/
  bootstrap/
  config/
  public/
  routes/
  Modules/

wayfinder/
  src/
  bin/
  stubs/
  tests/

This split helps keep application structure clear while preserving a reusable core.

Screenshots And Demo

This repo will include:

• starter application screenshots
• example application screenshots
• one simple architecture diagram
• terminal output for generators or architecture linting

If a live demo is added later, it can be linked here. For now, screenshots and short examples are enough to show the framework direction clearly.

Current Status

Stackmint is actively developed.

The framework code and starter repos are private for now while the public-facing showcase, docs, and release structure are being prepared more carefully.

This public repo is intended to show:

• the framework direction
• the architecture philosophy
• the application shape
• the kinds of problems Stackmint is built to solve

Roadmap

• Continue refining public documentation
• Improve the starter application experience
• Publish more example applications and screenshots
• Evolve optional modules over time
• Prepare the framework ecosystem for broader public release

Learn More

• FAQ
• Repo Status
• Roadmap
• Routing Example
• Model Example
• Query Example
• Service Example

If you are interested in collaboration, evaluation, or future access, this repo can later include contact details or an interest form once the public release process is further along.