Skip to content

Commit 4d8218b

Browse files
aguingandaguingand
committed
Add guidelines
1 parent b0e2503 commit 4d8218b

2 files changed

Lines changed: 230 additions & 0 deletions

File tree

‎resources/boost/guidelines/blueprint.blade.php‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
## Sharp Blueprint
2+
A Sharp Blueprint is a detailed implementation plan that helps AI agents write correct Sharp code. It bridges the gap between requirements and implementation by providing a structured specification for Sharp's unique patterns.
3+
4+
### Core Philosophy
5+
Sharp separates the data structure from its visual representation. A blueprint should clearly map domain models to Sharp components:
6+
- **Entity Lists**: The primary data table.
7+
- **Forms**: Data entry and validation.
8+
- **Show Pages**: Detailed read-only views.
9+
- **Commands**: Business logic triggers.
10+
- **State Handlers**: Lifecycle management.
11+
12+
### Blueprint Structure
13+
When asking an AI to create a blueprint, it should produce:
14+
1. **User Flows**: Step-by-step navigation through the feature.
15+
2. **Commands**: Required Artisan commands for scaffolding.
16+
3. **Models**: Detailed attribute, relationship, and cast definitions.
17+
4. **Sharp Components**: Specific configurations for Lists, Forms, Shows, and Commands.
18+
19+
---
20+
21+
## SaaS Invoicing System - Sharp Implementation Plan
22+
23+
### Overview
24+
A single-tenant admin panel for managing customers, products, invoices with line items, and tracking payments.
25+
26+
### User Flows
27+
#### Flow 1: Creating an Invoice
28+
1. User navigates to Invoices List -> "New"
29+
2. User selects a Customer (Select field with autocomplete)
30+
3. User sets invoice date and due date
31+
4. User adds line items via List field:
32+
- Select Product
33+
- Enter quantity
34+
- Line total auto-calculates (handled in model/transformer)
35+
5. Tax rate is entered
36+
6. Invoice saves as Draft status
37+
38+
#### Flow 2: Sending an Invoice
39+
1. User views a Draft invoice in its Show Page
40+
2. User clicks "Send" (Instance Command)
41+
3. Confirmation modal appears
42+
4. On confirm: status -> Sent, notification sent
43+
44+
### Models
45+
#### Model: Customer
46+
- **Attributes**: `name`, `email`, `phone`, `address`, `notes`
47+
- **Relationships**: `hasMany` Invoices
48+
49+
#### Model: Invoice
50+
- **Attributes**: `invoice_number`, `status` (Enum), `invoice_date`, `due_date`, `tax_rate`
51+
- **Relationships**: `belongsTo` Customer, `hasMany` InvoiceItem, `hasMany` Payment
52+
53+
### Sharp Components
54+
55+
#### InvoiceEntity
56+
- **Location**: `App\Sharp\Entities\InvoiceEntity`
57+
- **Config**:
58+
- `list`: `InvoiceList`
59+
- `show`: `InvoiceShow`
60+
- `form`: `InvoiceForm`
61+
- `state`: `InvoiceStateHandler`
62+
63+
#### InvoiceList
64+
- **Columns**:
65+
- `invoice_number`: label "Number", sortable
66+
- `customer:name`: label "Customer"
67+
- `invoice_date`: label "Date", sortable
68+
- `total`: label "Total", money format
69+
- `state`: label "Status", state badge
70+
- **Filters**: `InvoiceStatusFilter`, `DateRangeFilter`
71+
72+
#### InvoiceForm
73+
- **Layout**:
74+
- Section "General": `customer_id`, `invoice_date`, `due_date`
75+
- Section "Items": `items` (List field)
76+
- Section "Totals": `tax_rate`, `notes`
77+
- **Fields**:
78+
@verbatim
79+
<code-snippet name="Invoice Form List Field" lang="php">
80+
SharpFormListField::make('items')
81+
->setLabel('Items')
82+
->addItemField(
83+
SharpFormSelectField::make('product_id', $products)->setLabel('Product')
84+
)
85+
->addItemField(
86+
SharpFormTextField::make('quantity')->setLabel('Quantity')->setInputModeNumeric()
87+
)
88+
</code-snippet>
89+
@endverbatim
90+
91+
#### InvoiceShow
92+
- **Sections**:
93+
- Header: Number, Status, Customer Info
94+
- Content: `items` (Entity List section or List field)
95+
- Sidebar: `payments` (Entity List section)
96+
- **Commands**: `SendInvoiceCommand`, `RecordPaymentCommand`
97+
98+
#### InvoiceStateHandler
99+
@verbatim
100+
<code-snippet name="Invoice State Handler" lang="php">
101+
class InvoiceStateHandler extends SharpEntityStateHandler
102+
{
103+
public function buildStates(): void
104+
{
105+
$this->addState('draft', 'Draft', 'gray')
106+
->addState('sent', 'Sent', 'blue')
107+
->addState('paid', 'Paid', 'green')
108+
->addState('cancelled', 'Cancelled', 'red');
109+
}
110+
}
111+
</code-snippet>
112+
@endverbatim

‎resources/boost/guidelines/core.blade.php‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
## Sharp
2+
- Sharp is used by this application. Follow existing conventions for how and where it's implemented.
3+
- Sharp is a content management framework for Laravel that allows you to define user interfaces in PHP using structured configuration objects.
4+
- Sharp allows you to build Entity Lists, Forms, Show Pages, and Dashboards.
5+
6+
### Patterns
7+
Use `make()` static methods to initialize fields, columns, and other components.
8+
9+
#### Entity Lists
10+
Entity Lists are used to display a list of records.
11+
@verbatim
12+
<code-snippet name="Sharp Entity List" lang="php">
13+
use Code16\Sharp\EntityList\Fields\EntityListField;
14+
use Code16\Sharp\EntityList\Fields\EntityListFieldsContainer;
15+
use Code16\Sharp\EntityList\SharpEntityList;
16+
17+
class UserList extends SharpEntityList
18+
{
19+
protected function buildList(EntityListFieldsContainer $fields): void
20+
{
21+
$fields
22+
->addField(
23+
EntityListField::make('name')
24+
->setLabel('Name')
25+
->setSortable()
26+
)
27+
->addField(
28+
EntityListField::make('email')
29+
->setLabel('Email')
30+
);
31+
}
32+
}
33+
</code-snippet>
34+
@endverbatim
35+
36+
#### Forms
37+
Forms are used to create or edit records.
38+
@verbatim
39+
<code-snippet name="Sharp Form" lang="php">
40+
use Code16\Sharp\Form\Fields\SharpFormTextField;
41+
use Code16\Sharp\Form\Fields\SharpFormEditorField;
42+
use Code16\Sharp\Form\SharpForm;
43+
use Code16\Sharp\Utils\Fields\FieldsContainer;
44+
45+
class UserForm extends SharpForm
46+
{
47+
public function buildFormFields(FieldsContainer $formFields): void
48+
{
49+
$formFields
50+
->addField(
51+
SharpFormTextField::make('name')
52+
->setLabel('Name')
53+
->setRequired()
54+
)
55+
->addField(
56+
SharpFormEditorField::make('bio')
57+
->setLabel('Biography')
58+
);
59+
}
60+
}
61+
</code-snippet>
62+
@endverbatim
63+
64+
#### Show Pages
65+
Show Pages are used to display details of a single record.
66+
@verbatim
67+
<code-snippet name="Sharp Show Page" lang="php">
68+
use Code16\Sharp\Show\Fields\SharpShowTextField;
69+
use Code16\Sharp\Show\Layout\ShowLayout;
70+
use Code16\Sharp\Show\SharpShow;
71+
use Code16\Sharp\Utils\Fields\FieldsContainer;
72+
73+
class UserShow extends SharpShow
74+
{
75+
protected function buildShowFields(FieldsContainer $showFields): void
76+
{
77+
$showFields
78+
->addField(SharpShowTextField::make('name')->setLabel('Name'))
79+
->addField(SharpShowTextField::make('email')->setLabel('Email'));
80+
}
81+
82+
protected function buildShowLayout(ShowLayout $showLayout): void
83+
{
84+
$showLayout
85+
->addSection('General', function ($section) {
86+
$section->addColumn(6, function ($column) {
87+
$column->withFields('name', 'email');
88+
});
89+
});
90+
}
91+
}
92+
</code-snippet>
93+
@endverbatim
94+
95+
### Transformers
96+
Sharp uses Transformers to map your model data to the format expected by the UI.
97+
@verbatim
98+
<code-snippet name="Sharp Transformer" lang="php">
99+
public function find($id): array
100+
{
101+
return $this
102+
->setCustomTransformer('name', function($value, $user) {
103+
return strtoupper($value);
104+
})
105+
->transform(User::findOrFail($id));
106+
}
107+
</code-snippet>
108+
@endverbatim
109+
110+
### Common Classes & Namespaces
111+
- **Entity Lists:** `Code16\Sharp\EntityList\SharpEntityList`
112+
- **Forms:** `Code16\Sharp\Form\SharpForm`
113+
- **Show Pages:** `Code16\Sharp\Show\SharpShow`
114+
- **Dashboards:** `Code16\Sharp\Dashboard\SharpDashboard`
115+
- **Form Fields:** `Code16\Sharp\Form\Fields\...`
116+
- **Show Fields:** `Code16\Sharp\Show\Fields\...`
117+
- **Entity List Fields:** `Code16\Sharp\EntityList\Fields\...`
118+
- **Eloquent Updater:** `Code16\Sharp\Form\Eloquent\WithSharpFormEloquentUpdater`

0 commit comments

Comments
 (0)