# Project Technology Stack Specification

## Project Goal
Build a lightweight, fast, responsive, and highly reusable business application platform that runs efficiently on cPanel shared hosting.

The first application will manage:
- Quotations
- Invoices
- Delivery Notes
- Receipts
- Vouchers
- Other business documents

The architecture should also serve as the foundation for future systems such as:
- Inventory Management
- CRM
- HR Systems
- School Management
- POS
- ERP modules

---

# Core Technology Stack

## Backend
- PHP 8.3+
- Composer for dependency management
- PSR-4 autoloading and namespacing
- Lightweight MVC-inspired architecture
- No heavyweight framework dependency

### Routing
- FastRoute

Purpose:
- Lightweight and fast request routing
- Minimal overhead
- Framework-independent

---

## Database
- MariaDB (preferred over SQLite)

Reasons:
- Better concurrent write handling
- Included on most cPanel hosting environments
- Easier scaling
- Supports larger datasets and multiple users
- Better reporting and administration tooling

---

## Frontend

### HTMX
Purpose:
- AJAX interactions
- Partial page updates
- SPA-like responsiveness without a JavaScript SPA

Use cases:
- Dynamic forms
- Inline editing
- Search
- Pagination
- Modals
- Autocomplete
- Data tables

### Alpine.js
Purpose:
- Small client-side interactions

Use cases:
- Dropdowns
- Modals
- Tabs
- Show/hide sections
- Calculators
- Form state

### Tailwind CSS
Purpose:
- Utility-first styling
- Rapid UI development
- Consistent design system

Use for:
- Forms
- Tables
- Navigation
- Cards
- Status badges
- Responsive layouts

---

## Templating
- Twig (preferred)

Reasons:
- Clean separation between logic and presentation
- Reusable layouts and components
- Easier maintenance

---

## PDF Generation
- Dompdf

Purpose:
Generate:
- Quotations
- Invoices
- Receipts
- Delivery Notes
- Vouchers
- Printable reports

PDF templates should be rendered from HTML and styled using CSS.

---

# Architectural Principles

## Server-Rendered First
Render HTML on the server.

HTMX progressively enhances pages with:
- Partial updates
- Dynamic interactions
- Improved responsiveness

Avoid building a separate API and frontend unless future requirements demand it.

---

## Modular Design
Build reusable modules that can be shared across future systems.

Example modules:

BusinessCore/
├── Auth
├── Permissions
├── Users
├── Companies
├── Settings
├── Notifications
├── Documents
└── Reports

Applications should compose these modules rather than reimplement them.

---

# Suggested Project Structure

app/
├── Actions/
├── Controllers/
├── DTOs/
├── Middleware/
├── Models/
├── Repositories/
├── Services/
├── Components/
├── Helpers/
└── Views/

config/
public/
resources/
storage/
routes/
vendor/

resources/
├── views/
├── layouts/
├── components/
└── pdf/

---

# Coding Standards

- Use namespaces everywhere.
- Use PSR-4 autoloading.
- Keep controllers thin.
- Place business logic inside Services and Actions.
- Prefer dependency injection.
- Reuse components whenever possible.
- Avoid global helper sprawl.
- Keep modules loosely coupled.

---

# Design Philosophy

## Build a Platform, Not Just an App

Every feature should be designed for reuse.

Examples:
- DataTable component
- FormBuilder component
- SearchSelect component
- Modal component
- StatusBadge component
- Document engine
- Notification system
- Permission system

Future applications should reuse these building blocks.

---

# Document System Strategy

Use a generic document engine.

Document types:
- Quotation
- Invoice
- Delivery Note
- Receipt
- Voucher
- Purchase Order
- Credit Note
- Debit Note

The database should support adding new document types with minimal code changes.

---

# Performance Goals

- Fast page loads
- Low memory usage
- Minimal JavaScript
- Excellent shared hosting compatibility
- Simple deployment
- Long-term maintainability
- Scalable architecture for future products

---

# Final Stack Decision

Backend:
- PHP 8.3+
- Composer
- FastRoute
- Twig
- Dompdf

Database:
- MariaDB

Frontend:
- HTMX
- Alpine.js
- Tailwind CSS

Architecture:
- Modular
- Server-rendered first
- PSR-4
- MVC-inspired
- Reusable BusinessCore foundation