# ZEENO ERP POS — OpenCode Instructions

## Required Reading

Before planning, generating or editing code:

1. Read `PROJECT.md` completely.
2. Read all relevant files inside `docs/`.
3. Inspect existing migrations, models, services and tests.
4. Do not assume missing business rules.
5. Keep documentation updated when architecture changes.

## Technology Stack

- PHP 8.3
- Laravel compatible with PHP 8.3
- MySQL 8
- Laravel Blade
- Livewire
- Alpine.js
- Tailwind CSS
- Vite

Do not install packages requiring PHP 8.4 or newer.

## Architecture Rules

- Use a modular monolithic Laravel architecture.
- Keep controllers thin.
- Put business logic in service classes.
- Use Form Requests for validation.
- Use Policies and permissions for authorization.
- Use database transactions for financial and stock transactions.
- Use Eloquent relationships and query builders appropriately.
- Avoid unnecessary repository abstractions.
- Never place business logic inside Blade views.
- Use PHP enums for controlled statuses and transaction types.

## Accounting Rules

- Use the documented four-level Chart of Accounts.
- Only Level 4 postable accounts may accept transactions.
- Total debit must always equal total credit.
- Every posted financial transaction must create journal entries.
- Posted transactions cannot be directly edited or deleted.
- Corrections must use cancellation or reversal entries.
- Closed fiscal periods must reject new postings.
- Use `DECIMAL`, never `FLOAT`, for money.

## Inventory Rules

- Never change inventory only through the item master.
- Every stock movement must create a stock-ledger entry.
- Sales, purchases, returns, transfers and adjustments must update stock atomically.
- Respect company, branch, warehouse, batch and serial-number dimensions.
- Prevent negative stock unless company settings explicitly permit it.
- Use weighted-average costing unless another method is documented.

## Multi-tenant Business Rules

Every relevant transaction must include:

- `company_id`
- `branch_id`
- `fiscal_year_id`
- `warehouse_id` where applicable
- `created_by`

Users may access only assigned companies, branches and warehouses.

## UI Rules

- Use a modern enterprise interface.
- Use Tailwind CSS.
- Use Lucide icons.
- Avoid old Bootstrap admin-template styling.
- Keep pages responsive.
- Use compact, searchable data tables.
- Use three-dot menus for row actions.
- Include loading, empty, error and permission-denied states.
- Support keyboard-friendly transaction entry.
- Keep POS optimized for speed and touchscreen use.

## Development Workflow

For every module:

1. Analyze requirements.
2. Inspect related files.
3. Present a short implementation plan.
4. Create migrations.
5. Create models and relationships.
6. Create services and actions.
7. Add validation and authorization.
8. Create Livewire components and Blade views.
9. Add routes and navigation.
10. Add seeders or factories where appropriate.
11. Write feature and unit tests.
12. Run formatting and tests.
13. Report created and changed files.

## Safety Rules

- Do not delete existing working files without explaining why.
- Do not run destructive database commands without explicit approval.
- Do not use `migrate:fresh` on an existing database.
- Do not change accounting mappings silently.
- Do not install unverified or unnecessary packages.
- Verify package names, sources and PHP compatibility before installation.
- Preserve existing data and backward compatibility where practical.

## Output Expectations

At the end of every task, report:

- Files created
- Files modified
- Database changes
- Commands executed
- Tests executed
- Remaining work
- Any assumptions or risks