# DIE Subsidiary Management System

A comprehensive multi-tenant web application for managing subsidiary companies with advanced sales tracking, inventory control, and business intelligence capabilities.

## 🚀 Features

### 🏢 Multi-Tenant Architecture
- **Headquarters Control Panel**: Centralized management of all subsidiaries
- **Subsidiary Management**: Individual subsidiary operations and administration
- **Role-Based Access Control**: Three-tier user system (MHC Admin, Subsidiary Admin, Staff)
- **Multi-Language Support**: English, Spanish, French, and Portuguese

### 📊 Business Intelligence & Analytics
- **Real-time Dashboard**: KPI cards with sales, revenue, and performance metrics
- **Interactive Charts**: Sales performance visualization using Recharts
- **Inventory Analysis**: Stock levels, value calculations, and low-stock alerts
- **Advanced Reporting**: PDF generation with date range filtering
- **Activity Logging**: Complete audit trail of all user actions

### 🛍️ Sales & Point of Sale
- **Fast Sales Processing**: Quick transaction entry with real-time inventory updates
- **Client Management**: Customer information capture (NIF/NIN numbers)
- **Receipt Generation**: Professional receipt printing with company branding
- **Receipt Reprinting**: Search and reprint past receipts by number
- **Multi-Currency Support**: Configurable pricing and currency display

### 📦 Inventory & Services Management
- **Product Catalog**: Comprehensive item management with SKU tracking
- **Service vs Product**: Support for both physical products and services
- **Pricing Control**: Separate cost and sale price management
- **Category Organization**: Flexible categorization system
- **Stock Alerts**: Automated low-stock notifications

### 👥 User Management
- **Multi-Level Users**: Headquarters admins, subsidiary admins, and staff
- **Secure Authentication**: Passport.js with session management
- **User Activity Tracking**: Complete user action logging
- **Subsidiary Assignment**: Users linked to specific subsidiaries

### 🎨 Customization & Branding
- **Logo Management**: Upload and manage company logos
- **Receipt Customization**: Custom slogans and branding per subsidiary
- **Theme Support**: Professional UI with customizable themes
- **Responsive Design**: Mobile, tablet, and desktop optimized

## 🛠️ Technology Stack

### Frontend
- **React 18**: Modern React with hooks and functional components
- **TypeScript**: Full type safety across the application
- **Vite**: Fast build tool and development server
- **Tailwind CSS**: Utility-first CSS framework
- **shadcn/ui**: Modern component library built on Radix UI
- **TanStack Query**: Advanced data fetching and caching
- **Wouter**: Lightweight client-side routing
- **React Hook Form**: Efficient form handling with validation
- **i18next**: Internationalization framework
- **Recharts**: Interactive chart library
- **Framer Motion**: Smooth animations and transitions

### Backend
- **Node.js**: JavaScript runtime
- **Express.js**: Web application framework
- **TypeScript**: Type-safe server-side development
- **Drizzle ORM**: Type-safe database ORM
- **PostgreSQL**: Primary database (with MySQL support)
- **Passport.js**: Authentication middleware
- **Express Session**: Session management
- **Multer**: File upload handling
- **Zod**: Runtime type validation

### Database Schema
- **Users**: Role-based user management
- **Subsidiaries**: Company branch information
- **Inventory**: Product and service catalog
- **Sales**: Transaction records with client details
- **Activity Logs**: Complete audit trail
- **Global Settings**: System-wide configuration

### Security & Authentication
- **Password Hashing**: Secure password storage using scrypt
- **Session Management**: Express sessions with PostgreSQL store
- **Role-Based Access**: Granular permissions system
- **Input Validation**: Zod schemas for all user inputs
- **File Upload Security**: Type and size validation for uploads

## 📱 Application Structure

### MHC (Headquarters) Features
- **Global Dashboard**: System-wide metrics and KPIs
- **Subsidiary Management**: Create, edit, and monitor subsidiaries
- **User Administration**: Manage users across all subsidiaries
- **Global Reports**: Consolidated reporting across all locations
- **System Settings**: Configure global system parameters
- **Activity Monitoring**: View all system activity logs

### Subsidiary Features
- **Local Dashboard**: Subsidiary-specific metrics
- **Sales Processing**: Point of sale functionality
- **Inventory Management**: Local stock control
- **Daily Reports**: Subsidiary-specific reporting
- **User Management**: Manage local staff
- **Settings**: Configure subsidiary-specific options

## 🚀 Getting Started

### Prerequisites
- Node.js 20.x or higher
- PostgreSQL database
- Git

### Installation

1. **Clone the repository**
   ```bash
   git clone <repository-url>
   cd subsidiary-management-system
   ```

2. **Install dependencies**
   ```bash
   npm install
   ```

3. **Environment Setup**
   ```bash
   # Database configuration
   DATABASE_URL=postgresql://user:password@localhost:5432/subsidiary_db
   
   # Session secret
   REPL_ID=your-session-secret
   
   # Optional: Database connection parameters
   PGHOST=localhost
   PGPORT=5432
   PGDATABASE=subsidiary_db
   PGUSER=your_username
   PGPASSWORD=your_password
   ```

4. **Database Setup**
   ```bash
   npm run db:push
   ```

5. **Start the application**
   ```bash
   npm run dev
   ```

6. **Access the application**
   - Open http://localhost:5000
   - Default admin credentials: `admin / admin`

### Production Deployment

1. **Build the application**
   ```bash
   npm run build
   ```

2. **Start production server**
   ```bash
   npm start
   ```

## 📊 API Endpoints

### Authentication
- `POST /api/login` - User authentication
- `POST /api/register` - User registration
- `POST /api/logout` - User logout
- `GET /api/user` - Get current user

### Subsidiaries
- `GET /api/subsidiaries` - List subsidiaries
- `POST /api/subsidiaries` - Create subsidiary
- `PATCH /api/subsidiaries/:id` - Update subsidiary
- `GET /api/subsidiaries/:id` - Get subsidiary details

### Inventory
- `GET /api/subsidiaries/:id/inventory` - List inventory
- `POST /api/subsidiaries/:id/inventory` - Create inventory item
- `PATCH /api/subsidiaries/:id/inventory/:itemId` - Update item
- `DELETE /api/subsidiaries/:id/inventory/:itemId` - Delete item

### Sales
- `GET /api/subsidiaries/:id/sales` - List sales
- `POST /api/subsidiaries/:id/sales` - Create sale
- `DELETE /api/subsidiaries/:id/sales/:saleId` - Delete sale
- `GET /api/subsidiaries/:id/sales/search` - Search receipts

### Reports
- `GET /api/reports/sales` - Sales reports with filtering
- `GET /api/global-settings/:key` - Get global settings

## 🔧 Configuration

### Database Configuration
The application supports both PostgreSQL and MySQL databases. Configure your database in `db.config.mjs`:

```javascript
export default {
  engine: 'postgresql', // or 'mysql'
  // Connection details handled via environment variables
};
```

### Multi-Language Setup
Add new languages by creating translation files in `client/src/locales/[language]/translation.json`.

### File Upload Configuration
Configure upload limits and file types in `server/routes.ts`:

```javascript
const upload = multer({
  limits: {
    fileSize: 5 * 1024 * 1024 // 5MB limit
  },
  fileFilter: (req, file, cb) => {
    const allowedTypes = ['image/jpeg', 'image/png'];
    cb(null, allowedTypes.includes(file.mimetype));
  }
});
```

## 🧪 Development

### Project Structure
```
├── client/                 # React frontend
│   ├── src/
│   │   ├── components/     # Reusable components
│   │   ├── pages/         # Page components
│   │   ├── hooks/         # Custom React hooks
│   │   ├── providers/     # Context providers
│   │   └── locales/       # i18n translations
├── server/                # Express backend
│   ├── routes.ts          # API routes
│   ├── auth.ts           # Authentication
│   ├── storage.ts        # Database operations
│   └── index.ts          # Server entry point
├── shared/               # Shared types and schemas
│   └── schema.ts         # Database schema and types
└── uploads/              # File uploads directory
```

### Database Schema Management
Use Drizzle Kit for schema changes:

```bash
# Push schema changes to database
npm run db:push

# Generate migrations (if needed)
npx drizzle-kit generate

# View database in Drizzle Studio
npx drizzle-kit studio
```

### Adding New Features

1. **Database Changes**: Update `shared/schema.ts`
2. **API Routes**: Add endpoints in `server/routes.ts`
3. **Frontend Components**: Create components in `client/src/components/`
4. **Pages**: Add new pages in `client/src/pages/`
5. **Translations**: Update language files in `client/src/locales/`

## 🔒 Security Features

- **Password Security**: Scrypt hashing with salt
- **Session Management**: Secure session handling
- **Input Validation**: Comprehensive Zod schema validation
- **File Upload Security**: Type and size restrictions
- **Role-Based Access**: Granular permission system
- **SQL Injection Protection**: Parameterized queries via Drizzle ORM
- **CSRF Protection**: Session-based request validation

## 📈 Performance Features

- **Caching**: TanStack Query for intelligent data caching
- **Code Splitting**: Optimized bundle loading
- **Image Optimization**: Efficient file handling
- **Database Indexing**: Optimized database queries
- **Memory Management**: Efficient in-memory storage option

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/new-feature`
3. Commit changes: `git commit -am 'Add new feature'`
4. Push to branch: `git push origin feature/new-feature`
5. Submit a pull request

## 📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

## 🆘 Support

For support, please contact the development team or create an issue in the repository.

## 🎯 Roadmap

- [ ] Mobile application (React Native)
- [ ] Advanced analytics dashboard
- [ ] Stripe payment integration
- [ ] Automated backup system
- [ ] Multi-warehouse support
- [ ] Advanced reporting with charts
- [ ] Barcode scanning support
- [ ] Email notification system