gufi-cli 0.1.50 → 0.1.52

package/docs/dev-guide/1-01-architecture.md

@@ -0,0 +1,358 @@
+---
+id: architecture
+title: "Architecture Overview"
+description: "How Gufi is built and why"
+icon: Layers
+category: dev
+part: 1
+---
+
+# Architecture Overview
+
+How Gufi is built and why
+
+## System Architecture
+
+Gufi follows a modern microservices architecture optimized for multi-tenancy, real-time updates, and developer experience.
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         CLIENTS                                 │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐        │
+│  │  Web App │  │ Mobile   │  │   CLI    │  │   API    │        │
+│  │ (React)  │  │  (PWA)   │  │  (Node)  │  │ Clients  │        │
+│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘        │
+│       │             │             │             │               │
+└───────┼─────────────┼─────────────┼─────────────┼───────────────┘
+        │             │             │             │
+        ▼             ▼             ▼             ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                      LOAD BALANCER                              │
+└───────────────────────────┬─────────────────────────────────────┘
+                            │
+        ┌───────────────────┼───────────────────┐
+        │                   │                   │
+        ▼                   ▼                   ▼
+┌───────────────┐  ┌───────────────┐  ┌───────────────┐
+│  Backend ERP  │  │    Views      │  │   WebSocket   │
+│   (Express)   │  │   Backend     │  │    Server     │
+│    :3000      │  │    :3003      │  │    :4000      │
+└───────┬───────┘  └───────┬───────┘  └───────┬───────┘
+        │                  │                   │
+        └──────────────────┼───────────────────┘
+                           │
+        ┌──────────────────┴──────────────────┐
+        │                                      │
+        ▼                                      ▼
+┌───────────────┐                    ┌───────────────┐
+│  PostgreSQL   │                    │     Redis     │
+│  (Primary DB) │                    │    (Cache)    │
+└───────────────┘                    └───────────────┘
+        │
+        ▼
+┌───────────────┐
+│    Worker     │
+│   (pg-boss)   │
+└───────────────┘
+```
+
+## Core Services
+
+### Backend ERP (Port 3000)
+
+The main API server handling:
+
+- Authentication and authorization
+- CRUD operations for all entities
+- Module and schema management
+- File uploads and storage
+- Business logic and validations
+
+**Tech Stack:**
+- Node.js with Express
+- JWT + HttpOnly cookie authentication
+- Zod for validation
+- pg (node-postgres) for database
+
+### Views Backend (Port 3003)
+
+Handles view-specific operations:
+
+- Package publishing and versioning
+- View code storage and retrieval
+- Developer accounts and billing
+- Cross-company module installations
+
+**Key Endpoints:**
+- `/packages` - Package CRUD
+- `/views` - Custom view management
+- `/developer` - Developer portal API
+
+### WebSocket Server (Port 4000)
+
+Real-time communication:
+
+- LISTEN/NOTIFY from PostgreSQL
+- Broadcasts changes to connected clients
+- Room-based subscriptions per company/table
+- Presence tracking
+
+**Protocol:**
+- Native WebSocket (not Socket.IO)
+- JSON message format
+- Heartbeat for connection health
+
+### Worker (pg-boss)
+
+Background job processing:
+
+- Scheduled automations
+- Email sending
+- Heavy computations
+- Data synchronization
+- External API calls
+
+**Features:**
+- Persistent job queue in PostgreSQL
+- Retry with exponential backoff
+- Dead letter queue for failures
+- Monitoring and alerting
+
+## Frontend Architecture
+
+### React Application
+
+Built with modern React patterns:
+
+```
+frontend/src/
+├── features/           # Feature-based organization
+│   ├── auth/          # Login, registration
+│   ├── tables/        # Table views and editing
+│   ├── modules/       # Module management
+│   └── ...
+├── shared/            # Shared components
+│   ├── ui/           # Base UI components
+│   ├── views/        # View system components
+│   ├── dialogs/      # Dialog components
+│   └── hooks/        # Custom hooks
+├── stores/           # Zustand state stores
+├── contexts/         # React contexts
+└── sdk/              # Gufi SDK for views
+```
+
+### State Management
+
+| Store | Purpose |
+|---|---|
+| **authStore** | User session, tokens |
+| **schemaStore** | Company schema cache |
+| **permissionsStore** | Permission cache |
+| **uiStore** | UI state (sidebar, dialogs) |
+
+Using Zustand for simple, type-safe state management.
+
+### Data Fetching
+
+Using Refine framework:
+
+- Automatic CRUD hooks
+- Caching and invalidation
+- Optimistic updates
+- Pagination helpers
+
+## Database Architecture
+
+### PostgreSQL as Core
+
+Why PostgreSQL:
+
+- JSONB for flexible schemas
+- Row-level security
+- LISTEN/NOTIFY for real-time
+- Excellent performance
+- Strong ACID compliance
+
+### Multi-Tenant Schema
+
+```
+PostgreSQL Instance
+├── core (schema)           # Platform data
+│   ├── users               # All users
+│   ├── companies           # All companies
+│   ├── modules             # Module definitions
+│   ├── entities            # Entity definitions
+│   └── automation_scripts  # Shared scripts
+│
+├── company_1 (schema)      # Company 1 data
+│   ├── m1_t1               # Module 1, Entity 1
+│   ├── m1_t2               # Module 1, Entity 2
+│   ├── __audit_log__       # Audit trail
+│   └── ...
+│
+├── company_2 (schema)      # Company 2 data
+│   └── ...
+└── ...
+```
+
+### Table Naming Convention
+
+Physical tables use IDs:
+
+```
+m{moduleId}_t{entityId}
+
+Example: m360_t4589
+         └── Module 360, Entity 4589
+```
+
+Logical names (products, customers) map to physical names via schema.
+
+## API Design
+
+### RESTful Endpoints
+
+```
+GET    /api/tables/:tableId           # List records
+GET    /api/tables/:tableId/:rowId    # Get record
+POST   /api/tables/:tableId           # Create record
+PUT    /api/tables/:tableId/:rowId    # Update record
+DELETE /api/tables/:tableId/:rowId    # Delete record
+```
+
+### Authentication Flow
+
+```
+1. Login → POST /api/auth/login
+   ← Access token (15min) + Refresh cookie (7days)
+
+2. API Request → GET /api/... + Authorization: Bearer {token}
+   ← Data response
+
+3. Token Expiring → POST /api/auth/refresh
+   ← New access token
+```
+
+### Response Format
+
+Success:
+```json
+{
+  "data": { ... },
+  "meta": {
+    "total": 100,
+    "page": 1,
+    "pageSize": 20
+  }
+}
+```
+
+Error:
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Price must be positive",
+    "details": { "field": "price" }
+  }
+}
+```
+
+## Security Model
+
+### Layers of Security
+
+1. **Network**: HTTPS, WAF, Rate limiting
+2. **Authentication**: JWT, refresh tokens, 2FA
+3. **Authorization**: Role-based, entity-level
+4. **Data**: Row-level security, tenant isolation
+5. **Audit**: Complete change tracking
+
+### Tenant Isolation
+
+Each request:
+
+```
+1. Extract company_id from JWT
+2. SET search_path TO company_{id}
+3. Execute query (sees only company data)
+4. RESET search_path
+```
+
+No cross-tenant queries possible at database level.
+
+## Caching Strategy
+
+### Redis Cache Layers
+
+| Layer | TTL | Purpose |
+|---|---|---|
+| **Schema** | 5 min | Company schemas |
+| **Permissions** | 1 min | User permissions |
+| **Queries** | 30 sec | Expensive queries |
+| **Sessions** | 7 days | User sessions |
+
+### Cache Invalidation
+
+Event-driven invalidation:
+
+```
+Record Changed → Invalidate related caches
+               → Notify WebSocket
+               → Clients refetch
+```
+
+## Deployment
+
+### Container Architecture
+
+```yaml
+services:
+  frontend:
+    image: gufi/frontend
+    ports: [5173, 8080]
+
+  backend:
+    image: gufi/backend
+    ports: [3000]
+    depends_on: [db, redis]
+
+  websocket:
+    image: gufi/websocket
+    ports: [4000]
+    depends_on: [db, redis]
+
+  worker:
+    image: gufi/worker
+    depends_on: [db, redis]
+
+  db:
+    image: postgres:15
+    volumes: [db_data]
+
+  redis:
+    image: redis:7
+```
+
+### Scaling
+
+| Component | Scale Strategy |
+|---|---|
+| Frontend | Horizontal (CDN + replicas) |
+| Backend | Horizontal (load balanced) |
+| WebSocket | Horizontal (Redis pub/sub) |
+| Worker | Horizontal (pg-boss handles) |
+| PostgreSQL | Vertical + Read replicas |
+| Redis | Cluster mode |
+
+## Performance Targets
+
+| Metric | Target |
+|---|---|
+| API Response (P95) | < 100ms |
+| Page Load | < 2s |
+| Time to Interactive | < 3s |
+| WebSocket Latency | < 50ms |
+| Database Query | < 50ms |
+
+Monitored continuously with alerting on degradation.