# System Overview - Unified Dashboard Architecture

## What You Have

A **unified dashboard platform** with two **completely independent modules**:

```
┌─────────────────────────────────────────────────────────┐
│        GLOBALE RC - UNIFIED OPERATIONS DASHBOARD          │
│                                                            │
│  User Authentication (Google OAuth) - Shared Only        │
│                          ↓                                │
│  ┌────────────────────────────────────────────────────┐  │
│  │  Navigation Tabs: Sales | Inventory               │  │
│  └────────────────────────────────────────────────────┘  │
│          ↙                                    ↘           │
│  ┌──────────────────────┐        ┌──────────────────────┐│
│  │  SALES MODULE        │        │ INVENTORY MODULE     ││
│  │                      │        │                      ││
│  │ Independent System #1│        │ Independent System #2││
│  │                      │        │                      ││
│  │ • Google Sheet #1    │        │ • Google Sheet #2    ││
│  │ • Sales Data         │        │ • Stock Data         ││
│  │ • Role: Commercial   │        │ • Role: Warehouse    ││
│  │ • No dependencies    │        │ • No dependencies    ││
│  └──────────────────────┘        └──────────────────────┘│
│                                                            │
└─────────────────────────────────────────────────────────┘
```

---

## Module 1: Sales Dashboard

**Purpose**: Track and analyze sales data  
**Status**: ✅ Fully Operational  
**Documentation**: See [DEVELOPMENT_SUMMARY.md](DEVELOPMENT_SUMMARY.md)

### Features
- 📊 Sales data visualization
- 🔍 Advanced filtering (Cliente, Zona, Comercial, etc.)
- 📈 Summary statistics
- 💰 Revenue tracking

### Data Source
- **Google Sheet**: DEFAULT_SPREADSHEET_ID
- **11 Columns**: Cliente, Zona, Comercial, Desconto, Prazo Pagamento Dias, Código, Referencia, Familia, Mês, Quant, Faturaçao

### Access Control
- **Admins**: Full access
- **Commercial**: Restricted to own data
- **Viewers**: View-only access

### Routes
```
GET  /dashboard              Main sales dashboard
GET  /get-sheets-data        Fetch filtered sales data
POST /set-spreadsheet-id     Configure sales sheet
```

---

## Module 2: Inventory Management

**Purpose**: Control warehouse stock levels  
**Status**: 🆕 Newly Added  
**Documentation**: See [INVENTORY_SETUP.md](INVENTORY_SETUP.md)

### Features
- 📦 Real-time stock levels
- 🚨 Low stock alerts (red highlighting)
- 🔍 Search & filter by code or location
- 📊 Inventory summary statistics

### Data Source
- **Google Sheet**: INVENTORY_SPREADSHEET_ID (must be configured)
- **25 Columns**: Linha, Quantidade em stock, Tipo, Ref, Modelo, Submodelo, Tipo de tampa, Medida, Tipo de Medida, Madeira, Laminado, Cor, Acabamento, Zinco/Inox, Estofo, Tecido, Renda, Conjunto, Asas, Qtd Asas, Cruz/Cristo, Fecho, Acessórios, Extras/Observações, Cliente

### Access Control
- **Admins**: Full access
- **Warehouse team**: Full access (if email added to WAREHOUSE_EMAILS)
- **Others**: Access denied

### Routes
```
GET  /inventory                      Main inventory dashboard
GET  /get-inventory-data             Fetch inventory data
POST /set-inventory-spreadsheet      Configure inventory sheet (admin only)
```

---

## Shared Infrastructure

### Authentication
- Single Google OAuth login for both modules
- One `credentials.json` needed
- Session management shared

### User Interface
- Unified navigation bar
- Consistent styling and theme
- Base template shared
- Responsive design for both

### Caching System
- Separate cache for each module
- 5-minute TTL (Time To Live)
- Automatic cache clearing on config changes

### Role-Based Access Control (RBAC)
```
Roles Available:
├── admin              → Access to ALL (Sales + Inventory)
├── comercial          → Access to SALES only
├── viewer             → Access to SALES (view-only)
└── warehouse          → Access to INVENTORY only
```

---

## Key Difference: Independence

### Sales Module Does NOT Know About Inventory
- ❌ No inventory data in sales sheet
- ❌ No dependency on inventory module
- ❌ Works perfectly even if inventory is offline
- ❌ Different Google Sheets

### Inventory Module Does NOT Know About Sales
- ❌ No sales data in inventory sheet
- ❌ No dependency on sales module
- ❌ Works perfectly even if sales is offline
- ❌ Different Google Sheets

### They Only Share
- ✅ User authentication (Google OAuth)
- ✅ Navigation menu
- ✅ Visual styling
- ✅ Role-based permissions system

---

## Configuration

### For Sales Module Only
Edit `app.py`:
```python
DEFAULT_SPREADSHEET_ID = "your-sales-sheet-id"
```

### For Inventory Module Only
Edit `app.py`:
```python
INVENTORY_SPREADSHEET_ID = "your-inventory-sheet-id"
WAREHOUSE_EMAILS = {
    "warehouse1@globalerc.com",
    "warehouse2@globalerc.com",
}
```

### Both Modules Independently Configurable
- Can add Sales sheet without Inventory
- Can add Inventory sheet without affecting Sales
- Can disable either module by not configuring it

---

## File Structure

```
app.py
├── Sales Routes (lines ~1292-?)
│   ├── /dashboard
│   ├── /get-sheets-data
│   └── /set-spreadsheet-id
│
└── Inventory Routes (lines ~4350-4500)
    ├── /inventory
    ├── /get-inventory-data
    └── /set-inventory-spreadsheet

templates/
├── base.html              (Shared header + nav)
├── dashboard.html         (Sales module)
└── inventory.html         (Inventory module)

Documentation/
├── README.md              (Overall info)
├── DEVELOPMENT_SUMMARY.md (Sales module details)
├── INVENTORY_SETUP.md     (Inventory setup guide)
└── SYSTEM_OVERVIEW.md     (This file)
```

---

## Deployment Considerations

### Each Module Independently
- Sales can be deployed separately
- Inventory can be deployed separately
- Either can be disabled by not configuring
- Database backups should cover both sheets

### For Operations Team
- **Sales down?** Inventory still works
- **Inventory down?** Sales still works
- **Both down?** Only authentication affected

### Scaling
- Can add more modules using same pattern
- Each module gets own Google Sheet
- Caching works per-module
- Performance independent

---

## Access Flow

### User Accesses App
```
1. User visits: https://your-domain/
2. Redirected to: /login
3. Google OAuth authentication
4. Redirected to: /dashboard (Sales by default)
5. Navigation tabs visible
6. User can click → Sales or Inventory tab
7. System checks role permissions
8. Shows appropriate module or "Access Denied"
```

### Permission Checking

**For Sales Module**:
```
Role = admin?          → YES → Show Sales ✓
Role = comercial?      → YES → Show Sales ✓
Role = viewer?         → YES → Show Sales ✓
Role = warehouse?      → NO  → Access Denied ✗
```

**For Inventory Module**:
```
Role = admin?          → YES → Show Inventory ✓
Role = warehouse?      → YES → Show Inventory ✓
Role = comercial?      → NO  → Access Denied ✗
Role = viewer?         → NO  → Access Denied ✗
```

---

## Maintenance & Updates

### Updating Sales Module
- Edit sales routes in `app.py`
- Update `dashboard.html` or `templates/dashboard.html`
- No impact on Inventory

### Updating Inventory Module
- Edit inventory routes in `app.py`
- Update `templates/inventory.html`
- No impact on Sales

### Adding New Module (Future)
- Follow same pattern as Inventory
- Add new routes to `app.py`
- Create new template
- Add navigation tab to `base.html`
- Define new role if needed

---

## Next Steps

### For Sales Module
- Already fully configured and operational
- See: [DEVELOPMENT_SUMMARY.md](DEVELOPMENT_SUMMARY.md)

### For Inventory Module
1. Create Google Sheet with inventory data
2. Share with Google OAuth account
3. Copy Sheet ID
4. Update `INVENTORY_SPREADSHEET_ID` in `app.py`
5. Add warehouse emails to `WAREHOUSE_EMAILS`
6. Restart Flask
7. Access `https://your-domain/inventory`

See: [INVENTORY_SETUP.md](INVENTORY_SETUP.md) for detailed steps

---

## Support

- **Sales questions?** → See [DEVELOPMENT_SUMMARY.md](DEVELOPMENT_SUMMARY.md)
- **Inventory questions?** → See [INVENTORY_SETUP.md](INVENTORY_SETUP.md)
- **Setup help?** → See [QUICKSTART.md](QUICKSTART.md)
- **Configuration?** → See [CONFIGURATION.md](CONFIGURATION.md)

---

## Summary

You have a **unified platform with two independent operations**:

| Aspect | Sales | Inventory |
|--------|-------|-----------|
| **Purpose** | Track sales | Track stock |
| **Status** | ✅ Active | 🆕 New |
| **Data Source** | Sales Google Sheet | Inventory Google Sheet |
| **Primary Users** | Commercial, Admins | Warehouse, Admins |
| **Columns** | 11 | 25 |
| **Dependencies** | None | None |
| **Can work alone?** | YES | YES |

**Key Principle**: Each module is completely independent. They only share authentication and UI framework.