# Investra Platform 💼

---

## 🚀 Core Features

### User Registration & Member Dashboard

- **Secure Authentication**: Sign-up/login system with role-based access control
- **Wallet Overview**: Real-time wallet balance and transaction history
- **Share Holdings**: View owned investment shares and their performance
- **ROI Tracking**: Track received returns on investment with detailed breakdown
- **Purchase History**: Complete share purchase history and transaction logs
- **Fund Management**: Deposit/withdrawal request interface with status tracking

### Share-Based Investment System

- **Dynamic Shares**: Purchase investment shares based on available projects
- **Share Attributes**: ROI percentages, investment types, start/end dates
- **Ownership Transfer**: Seamless share transfer when resold in marketplace
- **Automated ROI Distribution**: Auto-distributed returns to current share holders
- **Investment Lifecycle**: Admin-controlled progression (start → funding → payout → complete)

### Marketplace Functionality

- **Share Listings**: View available shares for sale (admin/member listed)
- **Sell Shares**: List owned shares for sale with user-controlled pricing
- **Share Trading**: Buy/sell investment shares between platform members
- **Price Discovery**: Market-driven pricing for share resales

### Wallet & Fund Flow Management

- **Member Wallet**: Centralized wallet for deposits, purchases, and withdrawals
- **Fee Structure**: Percentage-based fees on member withdrawals
- **Payment Integration**: Stripe integration and manual bank transfer support
- **Transaction Tracking**: Comprehensive audit trail for all financial activities

### Admin Panel

- **Investment Management**: Create/manage investments and generate shares
- **User Administration**: Manage platform users and their activities
- **Share Oversight**: Monitor share listings, payouts, and performance
- **Revenue Tracking**: Platform activity monitoring and revenue analytics
- **Variable Control**: Set share parameters and review investment progress
- **Invoice Generation**: Monthly invoice creation and automated email alerts

### Additional Features

- **Email Notifications**: Purchase confirmations, invoices, and system alerts
- **Investment Gauge**: Visual progress indicators showing deal completion percentage
- **Withdrawal Queue**: Request management system with status tracking
- **Frontend Sections**: Landing page, Projects showcase, Marketplace, Authentication

---

## 🛠️ Tech Stack

### Backend

- **Framework**: Laravel 12
- **Database**: MySQL / MariaDB
- **API Documentation**: Swagger/OpenAPI 3.0
- **Authentication**: Laravel Sanctum
- **Payment Processing**: Stripe Integration
- **Caching**: Redis/Memcache
- **Queue System**: Laravel Queues (for ROI distribution)
- **Email System**: Laravel Mail with automated notifications
- **File Storage**: Laravel Filesystem (local/cloud)

### Frontend

- **Admin Panel**: Laravel Blade Engine with Tailwind CSS
- **Member Dashboard**: RESTful API with JSON responses
- **Marketplace Interface**: Dynamic share listing and trading
- **Responsive Design**: Mobile-optimized user interface

### Development & Testing

- **Testing Framework**: Pest PHP
- **Code Quality**: Laravel Pint
- **Environment**: PHP 8.3+
- **Package Manager**: Composer

### Deployment

- **Web Server**: Apache / Nginx
- **Environment**: PHP 8.3+
- **Database**: MySQL 8.0+ / MariaDB 10.4+
- **Hosting**: cPanel / VPS / Cloud platforms

### Payment Gateways

- Integrated with:
    - **Stripe** (Primary payment processor)
    - **Manual Bank Transfer** (Admin-processed deposits/withdrawals)
    - Support for additional gateways as needed

---

## 🏗️ Architecture Overview

### Core Models

- **User**: Platform members and admin users with role-based permissions
- **Investment**: Core investment projects with funding goals and ROI parameters
- **Share**: Investment shares linked to projects with ownership tracking
- **Wallet**: Member wallet system for deposits, purchases, and withdrawals
- **Transaction**: Financial transaction tracking with comprehensive audit trails
- **ShareListing**: Marketplace listings for share resales
- **ROIDistribution**: Automated return distribution to share holders
- **WithdrawalRequest**: Member withdrawal requests with admin approval workflow

### Key Features

- **Share Ownership**: Dynamic ownership transfer system for marketplace trading
- **ROI Automation**: Scheduled distribution of returns to current share holders
- **Wallet Management**: Centralized fund management with fee calculations
- **Investment Lifecycle**: Admin-controlled project progression and completion tracking
- **Marketplace Trading**: Peer-to-peer share trading with price discovery
- **Revenue Tracking**: Platform fee collection and financial reporting

---

### Project assumptions

- Share owner_id null means owner is admin and it is created while admin list share to marketplace. These share not participate in any actions but user can purchase it from marketplace.
- For infinite and Fixed shares, capital will distribute automatically; but for renewable share, capital will distribute when admin trigger complete the project manually.

## 📂 Folder Structure

```plaintext
investra-backend/
├── app/                           # Application logic
│   ├── Http/Controllers/Api/V1/   # API controllers
│   │   ├── Auth/                  # Authentication controllers
│   │   ├── Member/                # Member dashboard controllers
│   │   ├── Admin/                 # Admin panel controllers
│   │   ├── Marketplace/           # Share marketplace controllers
│   │   └── InvestmentController.php # Investment management
│   ├── Models/                    # Eloquent models
│   │   ├── User.php              # Platform users
│   │   ├── Investment.php        # Investment projects
│   │   ├── Share.php          # Investment shares
│   │   ├── Wallet.php            # Member wallets
│   │   ├── Transaction.php       # Financial transactions
│   │   └── ShareListing.php   # Marketplace listings
│   ├── Services/                  # Business logic services
│   │   ├── WalletService.php     # Wallet management
│   │   ├── ROIService.php        # ROI distribution
│   │   └── ShareService.php   # Share operations
│   ├── Enums/                     # Enum classes for type safety
│   ├── Jobs/                      # Queue jobs (ROI distribution)
│   ├── Notifications/             # Email notification classes
│   └── Rules/                     # Custom validation rules
├── config/                        # Configuration files
├── database/                      # Database migrations & seeds
├── routes/                        # API and web routes
│   ├── api.php                    # API routes
│   ├── web.php                    # Web routes
│   ├── auth.php                   # Authentication routes
│   ├── admin.php                  # Admin routes
│   ├── member.php                 # Member routes
│   └── marketplace.php            # Marketplace routes
├── storage/                       # File storage and logs
├── tests/                         # Automated tests
└── .env                          # Environment configuration
```

## 🚀 Installation

### Prerequisites

- PHP 8.3 or higher
- Composer
- MySQL 8.0+ or MariaDB 10.4+
- Node.js & NPM (for frontend assets)
- Redis (recommended for caching and queues)

### Setup Instructions

1. **Clone the repository**

```bash
git clone <repository-url>
cd investra-backend
```

2. **Install PHP dependencies**

```bash
composer install
```

3. **Setup environment**

```bash
cp .env.example .env
# Edit .env file with your database and other configurations
```

4. **Generate application key**

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

5. **Run database migrations and seeders**

```bash
php artisan migrate --seed
```

6. **Install and build frontend assets**

```bash
npm install && npm run dev
```

7. **Create storage symlink**

```bash
php artisan storage:link
```

8. **Start the development server**

```bash
php artisan serve
```

The application will be available at `http://127.0.0.1:8000`

### API Documentation

Access the Swagger API documentation at:

```
http://127.0.0.1:8000/api/documentation
```

### Configuration

1. **Database**: Configure MySQL/MariaDB connection in `.env`
2. **Stripe Payment**: Add Stripe API keys for payment processing
3. **Email Service**: Configure SMTP settings for notifications
4. **Queue System**: Setup Redis for ROI distribution jobs
5. **File Storage**: Setup local or cloud storage for documents

### Production Deployment

1. **Optimize for production**

```bash
php artisan config:cache
php artisan route:cache
php artisan view:cache
composer install --optimize-autoloader --no-dev
```

2. **Setup queues for ROI distribution**

```bash
php artisan queue:work
```

3. **Configure web server** (Nginx/Apache)
4. **Setup SSL certificate**
5. **Configure backup and monitoring**

---

## 📱 API Endpoints

### Authentication

- `POST /api/v1/auth/login` - User login
- `POST /api/v1/auth/register` - User registration
- `POST /api/v1/auth/logout` - User logout

### Member Dashboard

- `GET /api/v1/member/dashboard` - Dashboard overview
- `GET /api/v1/member/wallet` - Wallet balance and history
- `GET /api/v1/member/shares` - Owned shares
- `GET /api/v1/member/transactions` - Transaction history
- `POST /api/v1/member/deposit` - Deposit funds
- `POST /api/v1/member/withdraw` - Request withdrawal

### Investments & Shares

- `GET /api/v1/investments` - Available investments
- `GET /api/v1/investments/{id}` - Investment details
- `POST /api/v1/shares/purchase` - Purchase investment share
- `GET /api/v1/shares/{id}` - Share details

### Marketplace

- `GET /api/v1/marketplace` - Available shares for sale
- `POST /api/v1/marketplace/list` - List share for sale
- `POST /api/v1/marketplace/purchase` - Buy share from marketplace
- `PUT /api/v1/marketplace/{id}/price` - Update share price

### Transactions

- `GET /api/v1/transactions` - Transaction history
- `GET /api/v1/transactions/{id}` - Transaction details

For complete API documentation, visit the Swagger UI after installation.

---

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

## 📄 License

This project is licensed under the MIT License.
