# DCT Company Secretary - Statutory Record Management System

A comprehensive web-based application designed for audit companies and company secretaries to manage statutory records, including company information, director appointments, and automated Register of Directors document generation.

## 📋 Table of Contents

- [About](#about)
- [Key Features](#key-features)
- [System Architecture](#system-architecture)
- [User Roles & Permissions](#user-roles--permissions)
- [Getting Started](#getting-started)
- [How to Use](#how-to-use)
- [Technical Stack](#technical-stack)
- [Documentation](#documentation)
- [Support](#support)

---

## 🎯 About

DCT Company Secretary is a multi-tenant web application that helps audit firms and company secretaries efficiently manage statutory records for their client companies. The system provides a centralized platform to:

- Maintain accurate company records
- Track director appointments and cessations
- Generate compliant Register of Directors documents
- Ensure data security through role-based access control
- Support multiple audit companies with complete data isolation

### Target Users

- **Audit Companies** - Firms that provide company secretarial services
- **Company Secretaries** - Professionals managing statutory records
- **Administrators** - Staff responsible for maintaining company data

---

## ✨ Key Features

### 1. **Company Management**
- Create and maintain company profiles
- Store company incorporation details (CI number, date of incorporation)
- Track company-specific information
- View company history and associated directors

### 2. **Director Management**
- Comprehensive director profiles with:
  - English and Chinese names
  - Aliases and previous names
  - HKID/CI numbers
  - Passport information
  - Residential addresses
  - Other directorships
  - Remarks and notes

### 3. **Director Appointments**
- Track appointment and cessation dates
- Link directors to multiple companies
- Maintain appointment history
- View active and past appointments

### 4. **Document Generation**
- **Automatic Register of Directors Export**
- Generate professional DOCX documents
- Include all required statutory information
- Support for Chinese characters
- One-click export functionality

### 5. **Multi-Tenant Architecture**
- Complete data isolation between audit companies
- Each audit company manages their own clients
- Super Admin oversight capability
- Secure data separation

### 6. **Role-Based Access Control**
- **Super Admin** - Full system access, manage audit companies
- **Admin** - Manage companies, directors, and appointments within their audit company
- **User** - View and manage assigned records

### 7. **Dashboard & Analytics**
- Real-time statistics
- Company overview
- Director counts
- Active appointment tracking

---

## 🏗️ System Architecture

### Data Model

```
Audit Company (Multi-tenant root)
├── Users (Admins and regular users)
├── Companies (Client companies)
│   └── Director Appointments
│       └── Directors (Shared pool)
└── Settings & Configuration
```

### Key Relationships

- **Audit Company** → Has many **Companies**
- **Audit Company** → Has many **Users**
- **Company** → Has many **Director Appointments**
- **Director** → Has many **Director Appointments**
- **Director Appointment** → Belongs to **Company** and **Director**

### Security Features

- User authentication via Laravel Breeze
- Role-based authorization middleware
- Audit company data isolation
- CSRF protection
- Secure password hashing
- Session management

---

## 👥 User Roles & Permissions

### Super Admin
- **Full System Access**
- Create and manage audit companies
- Create admin accounts for audit companies
- View all companies across all audit companies
- System-wide oversight

### Admin
- **Audit Company Management**
- Create and manage companies
- Create and manage directors
- Manage director appointments
- Export Register of Directors documents
- View all data within their audit company

### User
- **Limited Access**
- View companies within their audit company
- View directors within their audit company
- View director appointments
- Limited editing capabilities (as configured)

---

## 🚀 Getting Started

### Prerequisites

- **PHP 8.1+** with required extensions
- **MySQL 5.7+** or **MariaDB 10.3+**
- **Composer 2.x**
- **Node.js 16+** and **npm**

### Quick Installation

1. **Clone or download the project**
   ```bash
   cd /path/to/project
   ```

2. **Install dependencies**
   ```bash
   composer install
   npm install
   npm run build
   ```

3. **Configure environment**
   ```bash
   cp .env.example .env
   php artisan key:generate
   ```

4. **Set up database**
   - Create a MySQL database
   - Update `.env` with database credentials
   - Run migrations:
     ```bash
     php artisan migrate
     ```

5. **Start the server**
   ```bash
   php artisan serve
   ```

6. **Access the application**
   - Open http://127.0.0.1:8000 in your browser
   - Sign in with a seeded or imported super admin account

### First-Time Setup

1. **Sign in as Super Admin**
   - Registration is disabled
   - Use the super admin account created by seeding or SQL import
   - Change the password after the first login

2. **Create Audit Companies**
   - Log in as Super Admin
   - Navigate to "Audit Companies"
   - Create audit companies for your clients

3. **Create Admin Accounts**
   - For each audit company, create admin accounts
   - These admins will manage their respective companies

4. **Start Adding Data**
   - Admins can now add companies, directors, and appointments

---

## 📖 How to Use

### 1. Dashboard

Upon logging in, you'll see the dashboard displaying:
- Total companies managed
- Total directors in the system
- Active director appointments
- Quick access to company list

### 2. Managing Companies

**To add a new company:**
1. Click "Add Company" button
2. Fill in company details:
   - Company Name (required)
   - CI Number (required)
   - Date of Incorporation (required)
3. Click "Create Company"

**To view/edit a company:**
1. Click on the company name in the list
2. View company details and associated directors
3. Use action buttons to edit or manage directors

### 3. Managing Directors

**To add a new director:**
1. Navigate to "Directors" section
2. Click "Add Director"
3. Fill in director information:
   - English Name (required)
   - Chinese Name (optional)
   - Alias (optional)
   - Previous Name (optional)
   - HKID/CI Number (optional)
   - Passport Number & Issuing Country (optional)
   - Residential Address (optional)
   - Other Directorships (optional)
   - Remarks (optional)
4. Click "Create Director"

**To edit a director:**
1. Click on the director's name
2. Update information as needed
3. Click "Update Director"

### 4. Managing Director Appointments

**To appoint a director to a company:**
1. Go to a company's detail page
2. Click "Manage Directors" button
3. Click "Add Appointment"
4. Select director from dropdown
5. Set appointment date (required)
6. Optionally set cessation date
7. Add remarks if needed
8. Click "Create Appointment"

**To update an appointment:**
1. Go to company's appointments list
2. Click "Edit" on the appointment
3. Update dates or remarks
4. Click "Update Appointment"

**To remove an appointment:**
1. Click "Delete" on the appointment
2. Confirm deletion

### 5. Exporting Register of Directors

**To generate the document:**
1. Go to a company's detail page
2. Click the "Export DOCX" button (document icon)
3. The system will automatically generate a DOCX file containing:
   - Company name and CI number
   - Date of incorporation
   - Complete director information
   - Appointment and cessation dates
   - All statutory details
4. The file will download automatically

### 6. Managing Audit Companies (Super Admin Only)

**To create a new audit company:**
1. Navigate to "Audit Companies" section
2. Click "Create Audit Company"
3. Fill in company details:
   - Name (required)
   - Email (required, must be unique)
   - Phone (optional)
   - Address (optional)
   - Registration Number (optional)
   - Admin Name (required)
   - Admin Email (required)
   - Admin Password (required, min 8 characters)
4. Click "Create Audit Company"

**To add additional admins:**
1. Go to audit company detail page
2. Click "Add Admin"
3. Fill in admin details
4. Click "Add Admin"

---

## 🛠️ Technical Stack

### Backend
- **Framework:** Laravel 11.x
- **Language:** PHP 8.1+
- **Database:** MySQL/MariaDB
- **Authentication:** Laravel Breeze
- **Document Generation:** PhpOffice/PhpWord

### Frontend
- **Framework:** Blade Templates
- **Styling:** Tailwind CSS
- **Build Tool:** Vite
- **Icons:** SVG (inline)

### Key Libraries
- **Laravel Sanctum** - API authentication
- **PhpOffice/PhpWord** - DOCX generation
- **Laravel Breeze** - Authentication scaffolding

---

## 📚 Documentation

For detailed setup and deployment instructions, please refer to:

- **[Local Development Setup Guide](setup_guide/LOCAL_SETUP.md)** - Complete local installation instructions
- **[Shared Hosting Deployment Guide](setup_guide/SHARED_HOSTING_DEPLOYMENT.md)** - Production deployment guide

### Common Commands

```bash
# Start development server
php artisan serve

# Run database migrations
php artisan migrate

# Clear application cache
php artisan cache:clear
php artisan config:clear
php artisan view:clear
php artisan route:clear

# Build frontend assets
npm run build

# Development mode with hot-reload
npm run dev

# Fresh migration (deletes all data)
php artisan migrate:fresh
```

---

## 🔒 Security Features

- **Password Hashing** - All passwords are securely hashed using Laravel's built-in hashing
- **CSRF Protection** - All forms are protected against Cross-Site Request Forgery
- **SQL Injection Prevention** - Using Laravel's Eloquent ORM with parameter binding
- **XSS Protection** - Input sanitization and output escaping
- **Session Security** - Secure session management with encrypted cookies
- **Role-Based Access** - Middleware ensures users can only access authorized resources
- **Data Isolation** - Multi-tenant architecture ensures complete data separation

---

## 📊 Data Structure

### Companies Table
- `id` - Primary key
- `company_name` - Company name
- `ci_number` - Company Incorporation number
- `date_of_incorporation` - Incorporation date
- `audit_company_id` - Foreign key to audit company
- `created_at`, `updated_at` - Timestamps

### Directors Table
- `id` - Primary key
- `english_name` - Director's English name
- `chinese_name` - Director's Chinese name
- `alias` - Alternative name
- `previous_name` - Former name
- `hkid_or_ci_number` - HKID or CI number
- `passport_number` - Passport number
- `passport_issuing_country` - Issuing country
- `residential_address` - Address
- `other_directorships` - Other positions
- `remarks` - Additional notes
- `audit_company_id` - Foreign key to audit company
- `created_at`, `updated_at` - Timestamps

### Director Appointments Table
- `id` - Primary key
- `company_id` - Foreign key to companies
- `director_id` - Foreign key to directors
- `date_of_appointment` - Appointment date
- `date_of_ceasing` - Cessation date (nullable)
- `remarks` - Additional notes
- `created_at`, `updated_at` - Timestamps

---

## 🤝 Support

For questions, issues, or feature requests, please contact the development team.

### Common Issues

**Problem:** Cannot log in
- **Solution:** Ensure you've registered an account and verified your email if required

**Problem:** Cannot see companies
- **Solution:** Check that you're assigned to an audit company and have the correct role

**Problem:** Export not working
- **Solution:** Ensure PHP zip extension is enabled and temp folder is writable

**Problem:** Chinese characters not displaying correctly
- **Solution:** Ensure database uses utf8mb4 character set

---

## 📝 License

This application is proprietary software. All rights reserved.

---

## 🎉 Acknowledgments

Built with:
- [Laravel](https://laravel.com/) - The PHP Framework for Web Artisans
- [Tailwind CSS](https://tailwindcss.com/) - Utility-first CSS framework
- [PhpOffice/PhpWord](https://phpoffice.github.io/PhpWord/) - PHP library for working with Word documents

---

**DCT Company Secretary** - Streamlining statutory record management for audit companies and company secretaries.
