Skip to content
BranchesTags

Repository files navigation

Alsfoan - Construction Project Management System

A comprehensive Laravel-based web application for managing construction projects, financial operations, suppliers, subcontractors, and all related business processes. This system provides a complete solution for construction companies to track projects, manage accounts, handle purchases and sales, and maintain detailed records of all business activities.

📋 Table of Contents

🎯 Overview

Alsfoan is a full-featured project management system designed specifically for construction and engineering companies. It enables businesses to:

  • Manage multiple construction projects with detailed tracking
  • Handle financial operations including accounts, expenses, purchases, and sales
  • Maintain supplier and subcontractor relationships
  • Track materials and their price history
  • Manage documents and official correspondence
  • Generate price offers and manage project terms
  • Handle maintenance requests
  • Provide role-based access control for different user types

The system is built with Arabic language support and follows Laravel best practices for scalability and maintainability.

✨ Features

Project Management

  • Project Creation & Tracking: Create and manage construction projects with detailed information including location, financing, costs, and profit calculations
  • Project Terms: Define and manage project terms with associated costs
  • Project Images: Upload and manage multiple images per project
  • Project Payments: Track payments associated with projects
  • Project Status: Monitor project status and progress

Financial Management

  • Account Management: Create and manage accounts for suppliers, subcontractors, projects, and admin
  • Account Transactions: Track all financial transactions between accounts
  • Account Transfers: Transfer funds between different accounts
  • Expense Tracking: Record and manage expenses with tax calculations
  • Purchase Management: Track purchases from suppliers and subcontractors
  • Sales Management: Record and manage sales transactions
  • Payment Processing: Handle various payment types (bank, cash, cheque, card)

Supplier & Subcontractor Management

  • Supplier Management: Maintain supplier database with contact information, tax details, and contract information
  • Subcontractor Management: Manage subcontractor information and relationships
  • Account Association: Link accounts to suppliers and subcontractors for financial tracking

Material Management

  • Material Catalog: Maintain a catalog of materials with pricing
  • Price History: Track material price changes over time
  • Material Types: Categorize materials by type

Document Management

  • Document Types: Define custom document types
  • Document Storage: Upload and manage documents with expiry dates
  • Entity Association: Link documents to various entities (suppliers, subcontractors, etc.)

Price Offers & Official Letters

  • Price Offers: Create and manage price offers for new projects
  • Recipients Management: Track price offer recipients
  • Official Letters: Generate and manage official correspondence
  • New Project Prices: Manage pricing for new project proposals

Maintenance Management

  • Maintenance Requests: Create and track maintenance requests
  • Status Tracking: Monitor maintenance request status (new, transferred, done)
  • User Assignment: Assign maintenance requests to users

User & Access Control

  • Role-Based Access Control (RBAC): Implemented using Spatie Laravel Permission
  • Multiple User Roles: Admin, Accountant, Engineer, and Client roles
  • Permission Management: Granular permission system for all features
  • User Management: Create, edit, and manage user accounts

🛠 Technology Stack

Backend

  • PHP 8.1+: Modern PHP with type hints and attributes
  • Laravel 10.10: Robust PHP framework for web applications
  • Laravel Sanctum: API authentication
  • Laravel Fortify: Authentication services
  • Laravel Jetstream: Application scaffolding with Livewire
  • Livewire: Full-stack framework for building dynamic interfaces
  • Spatie Laravel Permission: Role and permission management
  • Intervention Image: Image processing and manipulation
  • Guzzle HTTP: HTTP client for external API calls

Frontend

  • Vite: Next-generation frontend build tool
  • Bootstrap 4: CSS framework for responsive design
  • jQuery: JavaScript library for DOM manipulation
  • DataTables: Advanced tables with sorting, filtering, and pagination
  • Select2: Enhanced select boxes
  • Summernote: WYSIWYG editor
  • SweetAlert2: Beautiful alert dialogs
  • Chart.js: Data visualization
  • FullCalendar: Calendar widget
  • DateRangePicker: Date range selection
  • Font Awesome: Icon library

Database

  • MySQL/MariaDB: Relational database management system
  • Eloquent ORM: Laravel's database abstraction layer

Development Tools

  • Laravel Pint: Code style fixer
  • PHPUnit: Testing framework
  • Laravel Sail: Docker development environment

📦 Requirements

  • PHP >= 8.1
  • Composer
  • Node.js >= 16.x and NPM
  • MySQL >= 5.7 or MariaDB >= 10.3
  • Web server (Apache/Nginx)
  • Git

🚀 Installation

1. Clone the Repository

git clone https://github.com/AwadGorg/alsfoan.git
cd alsfoan

2. Install PHP Dependencies

composer install

3. Install Node Dependencies

npm install

4. Environment Configuration

Copy the environment file and configure it:

cp .env.example .env
php artisan key:generate

Edit the .env file with your database credentials and application settings:

APP_NAME=Alsfoan
APP_ENV=local
APP_KEY=base64:...
APP_DEBUG=true
APP_URL=http://localhost

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=alsfoan
DB_USERNAME=your_username
DB_PASSWORD=your_password

5. Database Setup

Create your database and run migrations:

php artisan migrate
php artisan db:seed

The seeder will create:

  • Default roles (admin, accountant, engineer, client)
  • Admin user account
  • All necessary permissions

6. Build Frontend Assets

For development:

npm run dev

For production:

npm run build

7. Storage Link

Create a symbolic link for storage:

php artisan storage:link

8. Start the Development Server

php artisan serve

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

⚙️ Configuration

Authentication

The application uses Laravel Fortify and Jetstream for authentication. Configure these in:

  • config/fortify.php
  • config/jetstream.php

Permissions

Role and permission management is handled by Spatie Laravel Permission. Configuration is in:

  • config/permission.php

File Storage

Configure file storage in config/filesystems.php. The default storage is set to public for uploaded files.

🗄 Database Setup

The application includes comprehensive database migrations for:

  • Users & Authentication: Users, password resets, two-factor authentication
  • Projects: Projects, project terms, project images, project payments
  • Financial: Accounts, account transactions, expenses, payments
  • Business Entities: Suppliers, subcontractors, materials, material price history
  • Transactions: Purchases, sales
  • Documents: Document types, documents
  • Management: Maintenances, price offers, price offer recipients, new project prices, official letters, expense terms
  • Permissions: Roles and permissions (via Spatie)

Run migrations:

php artisan migrate

📁 Project Structure

alsfoan/
├── app/
│   ├── Actions/          # Fortify and Jetstream actions
│   ├── Console/          # Artisan commands
│   ├── Exceptions/       # Exception handlers
│   ├── Http/
│   │   ├── Controllers/
│   │   │   └── Dashboard/  # Main application controllers
│   │   ├── Middleware/     # Custom middleware
│   │   └── Requests/       # Form request validation
│   ├── Models/          # Eloquent models
│   ├── Providers/       # Service providers
│   └── View/
│       └── Components/  # Blade components
├── bootstrap/           # Application bootstrap files
├── config/              # Configuration files
├── database/
│   ├── factories/       # Model factories
│   ├── migrations/      # Database migrations
│   └── seeders/         # Database seeders
├── public/              # Public assets
│   ├── dist/            # Compiled assets
│   └── plugins/         # Third-party plugins
├── resources/
│   ├── css/             # Stylesheets
│   ├── js/              # JavaScript files
│   ├── lang/            # Language files (Arabic)
│   ├── markdown/        # Markdown content
│   └── views/           # Blade templates
│       ├── dashboard/   # Dashboard views
│       ├── auth/        # Authentication views
│       └── components/  # Reusable components
├── routes/              # Route definitions
├── storage/             # Storage directory
├── tests/               # Test files
└── vite.config.js       # Vite configuration

🔑 Key Modules

Projects Module

Located in app/Http/Controllers/Dashboard/ProjectController.php

  • Create, read, update, delete projects
  • Manage project terms and images
  • Track project payments
  • Calculate project costs, values, and profits

Accounts Module

Located in app/Http/Controllers/Dashboard/AccountController.php

  • Manage financial accounts
  • Track account transactions
  • Transfer funds between accounts
  • Print account statements

Suppliers & Subcontractors

Located in app/Http/Controllers/Dashboard/SupplierController.php and SubcontractorController.php

  • Manage supplier and subcontractor information
  • Link accounts to entities
  • Track purchases and expenses

Materials Module

Located in app/Http/Controllers/Dashboard/MaterialController.php

  • Manage material catalog
  • Track price history
  • Categorize materials

Purchases & Sales

Located in app/Http/Controllers/Dashboard/PurchaseController.php and SaleController.php

  • Record purchases from suppliers/subcontractors
  • Record sales transactions
  • Calculate taxes and totals

Documents Module

Located in app/Http/Controllers/Dashboard/DocumentController.php

  • Define document types
  • Upload and manage documents
  • Track document expiry dates

👥 User Roles & Permissions

The system includes four main roles:

Admin

  • Full access to all features
  • User and role management
  • System configuration

Accountant

  • Financial management (accounts, expenses, purchases, sales)
  • Project viewing and editing
  • Supplier and subcontractor management
  • Document management
  • Maintenance request management

Engineer

  • View projects
  • View dashboard

Client

  • View assigned projects only

Permissions are managed through Spatie Laravel Permission package, allowing granular control over feature access.

💻 Usage

Accessing the Application

  1. Navigate to the application URL (default: http://localhost:8000)
  2. Login with admin credentials (created during seeding)
  3. Access the dashboard to view overview statistics

Creating a Project

  1. Navigate to Projects → Create New Project
  2. Fill in project details:
    • Client selection
    • Project name, location (city, region, plot number)
    • Financing information (bank, amounts)
    • Cost and value calculations
    • Tax information
  3. Add project terms with associated costs
  4. Upload project images
  5. Save the project

Managing Accounts

  1. Navigate to Accounts
  2. Create accounts for suppliers, subcontractors, projects, or admin
  3. Set opening balances
  4. View account transactions
  5. Transfer funds between accounts
  6. Print account statements

Recording Purchases

  1. Navigate to Purchases → Create New Purchase
  2. Select supplier or subcontractor
  3. Choose associated project and project term
  4. Enter purchase details (invoice number, date, type)
  5. Add quantity, unit price, and tax percentage
  6. Save the purchase

Managing Expenses

  1. Navigate to Expenses → Create New Expense
  2. Select account and entity (supplier/subcontractor)
  3. Enter expense details
  4. Link to purchase if applicable
  5. Save the expense

🔧 Development

Running Tests

php artisan test

Code Style

The project uses Laravel Pint for code formatting:

./vendor/bin/pint

Database Seeding

Seed the database with default data:

php artisan db:seed

Or seed specific seeders:

php artisan db:seed --class=RolesSeeder
php artisan db:seed --class=AdminSeeder

Clearing Cache

Clear application cache:

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

🤝 Contributing

Contributions are welcome! Please follow these steps:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/AmazingFeature)
  3. Commit your changes (git commit -m 'Add some AmazingFeature')
  4. Push to the branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

Please ensure your code follows Laravel coding standards and includes appropriate tests.

📝 License

This project is open-sourced software licensed under the MIT license.

👤 Author

Awad Gorg

🙏 Acknowledgments

  • Laravel Framework
  • Laravel Jetstream & Fortify
  • Spatie Laravel Permission
  • All contributors and open-source libraries used in this project

For more information or support, please open an issue on the GitHub repository.

About

Alsfoan - Construction Project Management System

Topics

laravel

Resources

Readme
Apache-2.0 license
Activity

Stars

0 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages