# DCT Company Secretary - Local Development Setup Guide

This guide will walk you through setting up the DCT Company Secretary Statutory Record application on your local development machine.

## Prerequisites

Before you begin, ensure you have the following installed on your system:

### Required Software

1. **PHP 8.1+**
   - Check version: `php -v`
   - Required extensions: `BCMath`, `Ctype`, `cURL`, `DOM`, `Fileinfo`, `JSON`, `Mbstring`, `OpenSSL`, `PCRE`, `PDO`, `Tokenizer`, `XML`, `Zip`

2. **Composer 2.x**
   - Check version: `composer -V`
   - Download: https://getcomposer.org/download/

3. **MySQL 5.7+ or MariaDB 10.3+**
   - Check version: `mysql -V`
   - Create a database for the application

4. **Node.js 16+ and npm** (for Laravel Breeze assets)
   - Check version: `node -v` and `npm -v`
   - Download: https://nodejs.org/

## Installation Steps

### Step 1: Clone or Copy the Project

```bash
# If using Git
git clone <repository-url> company-secretary
cd company-secretary

# Or copy the project files to your desired location
```

### Step 2: Install PHP Dependencies

```bash
composer install
```

This will install all required PHP packages including:
- Laravel Framework
- Laravel Breeze (authentication)
- PhpOffice/PhpWord (DOCX generation)

### Step 3: Create Environment File

```bash
cp .env.example .env
```

### Step 4: Configure Database

Edit the `.env` file and update the database settings:

```env
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=company_secretary
DB_USERNAME=your_username
DB_PASSWORD=your_password
```

Create the database in MySQL:

```sql
CREATE DATABASE company_secretary CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

### Step 5: Generate Application Key

```bash
php artisan key:generate
```

### Step 6: Run Database Migrations

```bash
php artisan migrate
```

This will create the following tables:
- `users` - User authentication
- `companies` - Company records
- `directors` - Director records  
- `director_appointments` - Director appointment records

### Step 7: Install Frontend Assets (Laravel Breeze)

```bash
npm install
npm run build
```

For development with hot-reload:
```bash
npm run dev
```

### Step 8: Start Development Server

```bash
php artisan serve
```

The application will be available at: **http://localhost:8000**

## First Time Usage

### Step 1: Register a User Account

1. Navigate to http://localhost:8000
2. Click "Register" in the top navigation
3. Fill in your name, email, and password
4. Click "Register" to create your account

### Step 2: Start Using the Application

1. **Dashboard** - View overview of companies and quick stats
2. **Companies** - Add and manage company records
3. **Directors** - Add and manage director records
4. **Appointments** - Link directors to companies with appointment dates
5. **Export** - Generate DOCX files for Register of Directors

## Common Commands

### Clear Application Cache

```bash
php artisan cache:clear
php artisan config:clear
php artisan view:clear
php artisan route:clear
```

### Rebuild Everything

```bash
php artisan optimize:clear
composer dump-autoload
npm run build
```

### Fresh Migration (Warning: Deletes All Data)

```bash
php artisan migrate:fresh
```

## Troubleshooting

### Error: Class not found

```bash
composer dump-autoload
```

### Error: Permission denied (storage/logs)

```bash
chmod -R 775 storage
chmod -R 775 bootstrap/cache
```

### Error: SQLSTATE Connection refused

- Ensure MySQL is running
- Verify database credentials in `.env`
- Check if database exists

### Chinese Characters Display Issues

Ensure your database uses `utf8mb4` character set:

```sql
ALTER DATABASE company_secretary 
CHARACTER SET utf8mb4 
COLLATE utf8mb4_unicode_ci;
```

## Application Structure

```
app/
├── Http/Controllers/
│   ├── CompanyController.php
│   ├── DirectorController.php
│   ├── DirectorAppointmentController.php
│   ├── DashboardController.php
│   └── CompanyRegisterExportController.php
├── Models/
│   ├── Company.php
│   ├── Director.php
│   └── DirectorAppointment.php
database/
├── migrations/
│   ├── 2024_01_01_000001_create_companies_table.php
│   ├── 2024_01_01_000002_create_directors_table.php
│   └── 2024_01_01_000003_create_director_appointments_table.php
resources/views/
├── layouts/app.blade.php
├── dashboard.blade.php
├── companies/
├── directors/
└── appointments/
```

## Support

For questions or issues, please contact the development team.

---

**DCT Company Secretary** - Statutory Record Management System