# Step 1 Setup: Registration, Onboarding and Business Profile

Built for **Laravel 13** (needs **PHP 8.3+**, Composer, MySQL 8).

## 1. Create the Laravel project

```bash
composer create-project laravel/laravel biashara
cd biashara
```

(If the installer asks about a starter kit, choose **None**. This project has its own login pages.)

## 2. Configure .env

Open `.env` and set:

```env
APP_NAME="Biashara"
APP_ENV=local
APP_DEBUG=true          # detailed error pages while developing (set false on live server!)
APP_URL=http://localhost:8000
APP_TIMEZONE=Africa/Nairobi

LOG_CHANNEL=daily       # one log file per day in storage/logs
LOG_LEVEL=debug

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=biashara
DB_USERNAME=root
DB_PASSWORD=
```

Create the empty database `biashara` in MySQL (phpMyAdmin or `CREATE DATABASE biashara;`).

> If `APP_TIMEZONE` has no effect, set `'timezone' => 'Africa/Nairobi'` in `config/app.php`.

## 3. Copy the Step 1 files

Copy the folders from this package into your project, **replacing** files when asked:

- `app/` (Models, Controllers, Requests, Middleware, Services, Support)
- `database/migrations/` and `database/seeders/`
- `resources/views/`
- `routes/web.php`

## 4. Run migrations, seed plans and link storage

```bash
php artisan migrate
php artisan db:seed
php artisan storage:link     # makes uploaded logos viewable
```

## 5. Start the app

```bash
php artisan serve
```

Open http://localhost:8000, register, complete onboarding, and you'll land on the dashboard
with the free Starter plan active for 12 months.

## 6. Debugging tools (recommended)

**Laravel Telescope** shows every request, query, error and log in a dashboard:

```bash
composer require laravel/telescope --dev
php artisan telescope:install
php artisan migrate
```

Then visit http://localhost:8000/telescope

**Logs**: errors and our own `Log::info` messages (new registrations, onboarding) are in
`storage/logs/laravel-YYYY-MM-DD.log`.

**Live log watching** in a second terminal:

```bash
php artisan pail
```

## Common errors

| Error | Fix |
|---|---|
| `SQLSTATE[HY000] [1049] Unknown database` | Create the database named in `DB_DATABASE` |
| `Starter plan not found. Run: php artisan db:seed` | Run `php artisan db:seed` |
| Logo uploads but image is broken | Run `php artisan storage:link` and check `APP_URL` matches your browser address |
| `419 Page Expired` on forms | Session expired; refresh the page. Make sure every form has `@csrf` |
| `Too Many Requests` on login | Login is limited to 5 attempts per minute; wait 60 seconds |

## What's included

- Registration with Kenyan phone validation (0712..., +254..., 0110... all accepted and stored as 2547/2541 format, ready for M-Pesa and WhatsApp)
- Login with "remember me", rate limiting and deactivated-account check
- Onboarding: business name, product/service/both, KRA PIN (validated format, unique), VAT status, logo upload, contacts, all 47 counties, M-Pesa Paybill/Till, bank details, default invoice terms
- Automatic 12-month free Starter subscription on onboarding
- Users who skip onboarding are redirected back to it
- Business settings page to edit everything later, including logo replacement and document number prefixes
- Dashboard showing the plan and days remaining
- Subscription plans and Kenyan tax rates seeded