sea-dev 1.0.0

package/docs/on-prem-deployment-spec.md

@@ -0,0 +1,378 @@
+# Sea.dev — On-Premises Deployment Specification
+
+**Version:** 1.0
+**Date:** March 2026
+**Classification:** Confidential
+
+---
+
+## 1. Server Specifications & Roles
+
+### 1.1 Application Servers
+
+Host the web application, API layer, background workers, and document conversion services.
+
+| Spec | Requirement |
+|------|-------------|
+| CPU | 32+ cores (x86_64) |
+| RAM | 64 GB |
+| Storage | 200 GB NVMe SSD |
+| OS | Ubuntu 22.04 LTS / RHEL 8+ |
+| Container Runtime | containerd 1.7+ (Kubernetes) or Docker 24+ |
+| Network | 10 Gbps |
+| Nodes (HA) | 3+ |
+
+### 1.2 Database & Storage Servers
+
+Host the relational database, caching layer, and S3-compatible object storage for documents.
+
+| Spec | Requirement |
+|------|-------------|
+| CPU | 16+ cores |
+| RAM | 64+ GB |
+| Storage | 1+ TB NVMe SSD (RAID-10) + 200 GB SSD (WAL) |
+| OS | Ubuntu 22.04 LTS / RHEL 8+ |
+| Nodes (HA) | 2 (primary + standby) |
+
+### 1.3 AI / GPU Servers
+
+Host the LLM inference engine and OCR processing pipeline. Requires NVIDIA GPU hardware with CUDA 12.2+.
+
+| Spec | Requirement |
+|------|-------------|
+| CPU | 32+ cores |
+| RAM | 128+ GB |
+| GPU | 2–4× NVIDIA A100 80GB or H100 |
+| Storage | 1 TB NVMe SSD (model weights) |
+| OS | Ubuntu 22.04 LTS + NVIDIA drivers 535+ |
+| CUDA | 12.2+ |
+| Nodes | 2+ |
+
+GPU memory requirements vary by model selection:
+
+| Model | GPU Memory (FP16) | Recommended Configuration |
+|-------|-------------------|--------------------------|
+| Llama 3.1 70B | ~140 GB | 2× A100 80GB |
+| Mixtral 8x22B | ~80 GB (quantized) | 2× A100 80GB |
+| Qwen 2.5 72B | ~144 GB | 2× A100 80GB |
+| Llama 3.1 8B (lightweight) | ~16 GB | 1× A100 40GB |
+
+### 1.4 Total Server Count
+
+| Role | Nodes | Purpose |
+|------|-------|---------|
+| Application | 3+ | Web, API, workers |
+| Database & Storage | 2 | PostgreSQL, Redis, object storage |
+| GPU / AI | 2+ | LLM inference, OCR |
+| **Total** | **7+** | |
+
+### 1.5 Operating System & Virtualization
+
+All components run as containers with no host-level application dependencies beyond the container runtime. Supported environments include VMware vSphere 7+, KVM/QEMU, and bare-metal. GPU nodes require PCIe passthrough or NVIDIA vGPU.
+
+---
+
+## 2. Architecture Overview
+
+### 2.1 High-Level Architecture
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│                     Customer Network (Air-Gapped)                 │
+│                                                                    │
+│  Users ──▶ [ Reverse Proxy / TLS Termination ]                    │
+│                    │                │                               │
+│           [ Web Application ]  [ REST API ]                        │
+│                    │                │                               │
+│              [ Job Orchestration Engine ]                           │
+│                    │                │                               │
+│       [ Document Processing ]  [ Data Extraction ]                 │
+│              Workers                Workers                        │
+│                    │                │                               │
+│         ┌─────────┴────────────────┴──────────┐                   │
+│         │           Data Layer                 │                   │
+│         │  PostgreSQL  │  Redis  │  MinIO      │                   │
+│         └─────────────────────────────────────┘                   │
+│                                                                    │
+│         ┌─────────────────────────────────────┐                   │
+│         │           AI Layer                   │                   │
+│         │  LLM Inference (vLLM)  │  OCR Engine │                   │
+│         └─────────────────────────────────────┘                   │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+### 2.2 Core Components
+
+| Component | Technology | Purpose |
+|-----------|-----------|---------|
+| Web Application | Node.js 22 / React (SSR) | User-facing interface |
+| REST API | Node.js 22 / Fastify | Programmatic access and integrations |
+| Job Orchestration | Hatchet (self-hosted) | Workflow management, task scheduling, failure recovery |
+| Document Processing Workers | Node.js 22 + LibreOffice | Document conversion and preparation |
+| Data Extraction Workers | Node.js 22 | AI-powered structured data extraction |
+| Database | PostgreSQL 16 | Primary data store |
+| Cache | Redis 7+ | Session management and caching |
+| Object Storage | MinIO | S3-compatible document storage |
+| LLM Inference | vLLM (GPU-accelerated) | Large language model serving (OpenAI-compatible API) |
+| OCR Engine | Tesseract 5 + PaddleOCR | Document text recognition and layout analysis |
+| Reverse Proxy | nginx or Traefik | TLS termination, routing, load balancing |
+
+### 2.3 Air-Gapped Operation
+
+The platform is designed for fully air-gapped deployment. No outbound internet access is required after initial installation. All AI models, OCR engines, and dependencies are bundled in the installation package.
+
+---
+
+## 3. Network & Security Requirements
+
+### 3.1 Network Ports
+
+| Port | Service | Direction |
+|------|---------|-----------|
+| 443 | HTTPS (user-facing) | Inbound from users |
+| 80 | HTTP (redirect to HTTPS) | Inbound from users |
+| 5432 | PostgreSQL | Internal only |
+| 6379 | Redis | Internal only |
+| 9000 | Object Storage API | Internal only |
+| 8000 | LLM Inference API | Internal only |
+| 8080 | OCR Service | Internal only |
+
+All inter-service communication is internal to the deployment. No ports need to be exposed to the internet.
+
+### 3.2 Authentication & Identity
+
+The platform integrates with enterprise identity providers. No local account management or password storage is required.
+
+| Method | Protocol | Use Case |
+|--------|----------|----------|
+| SAML 2.0 | XML/HTTPS | SSO with ADFS, Okta, PingFederate, or equivalent |
+| OpenID Connect | OAuth 2.0 | SSO (alternative to SAML) |
+| LDAP / LDAPS | LDAP(S) :389/:636 | Direct Active Directory authentication |
+
+Session management uses encrypted server-side sessions stored in the database, with configurable duration and idle timeout policies.
+
+### 3.3 Encryption
+
+| Layer | Standard | Details |
+|-------|----------|---------|
+| Transport (external) | TLS 1.2+ (1.3 preferred) | Customer provides certificates or uses internal CA |
+| Transport (internal) | mTLS (optional) | Service mesh or Kubernetes network policies |
+| Data at rest (database) | AES-256 | PostgreSQL TDE or volume-level encryption (LUKS) |
+| Data at rest (storage) | AES-256 | MinIO server-side encryption (SSE-S3 or SSE-KMS) |
+| Application-level | AES-256-GCM | Sensitive fields encrypted before database storage |
+
+### 3.4 Network Isolation
+
+In Kubernetes deployments, network policies enforce strict service-to-service boundaries. Workers are restricted to backend services only. No component has external network access.
+
+---
+
+## 4. Data Handling & Compliance
+
+### 4.1 Data Residency
+
+All data remains on-premises within the customer's data center. There is zero data egress — no telemetry, analytics, or license callbacks. The platform is fully functional without internet connectivity.
+
+### 4.2 Data Storage
+
+| Data Type | Storage | Retention |
+|-----------|---------|-----------|
+| User accounts & sessions | PostgreSQL | Configurable (sessions expire per policy) |
+| Uploaded documents | MinIO (encrypted at rest) | Customer-configurable retention policy |
+| Extracted data & results | PostgreSQL + MinIO | Customer-configurable |
+| AI interaction logs | PostgreSQL (optional) | Customer-configurable; can be disabled |
+| Application logs | Local filesystem | Customer-configurable; exportable to SIEM |
+
+### 4.3 Audit Logging
+
+Comprehensive audit logging covers authentication events, data access, administrative actions, and (optionally) AI interactions. Logs are structured JSON and can be exported to the customer's SIEM platform (Splunk, ELK, etc.) via syslog or file-based export.
+
+### 4.4 Data Isolation
+
+Each deployment is a fully independent instance with its own database, storage, and encryption keys. Within a deployment, organization-level data isolation is enforced at the database layer.
+
+---
+
+## 5. Scalability & Performance Guidelines
+
+### 5.1 Scaling Characteristics
+
+| Component | Scaling | Guidance |
+|-----------|---------|----------|
+| Web Application / API | Horizontal (CPU-based) | 2 replicas support ~500 concurrent users |
+| Data Extraction Workers | Horizontal (queue-based, scale-to-zero) | 1 worker handles 5–10 concurrent extractions |
+| Document Conversion | Horizontal (queue-based, scale-to-zero) | 1 worker handles ~3 concurrent conversions |
+| LLM Inference | Vertical (GPU-bound) | Throughput depends on model size; continuous batching supported |
+| OCR Engine | Horizontal (CPU-bound) | 1 instance per 4 CPU cores |
+| Database | Vertical | Read replicas available for high-throughput scenarios |
+| Object Storage | Horizontal | Add nodes to distributed cluster |
+
+### 5.2 Performance Targets
+
+| Operation | Target |
+|-----------|--------|
+| Page load | < 500ms |
+| API response (simple query) | < 100ms |
+| Document upload to processing queue | < 2s |
+| Document extraction (per page) | 5–30s |
+| AI chat response | 2–15s |
+
+### 5.3 Reference Sizing (~100 Users, ~1,000 Documents/Day)
+
+| Resource | Recommendation |
+|----------|---------------|
+| Application replicas | 2–3 |
+| Extraction workers | 2–4 |
+| Conversion workers | 1–2 |
+| Database | 16 cores, 64 GB RAM, 1 TB SSD |
+| Object storage | 2 TB usable (grows with document volume) |
+| GPU | 2× A100 80GB (for 70B-class model) |
+
+---
+
+## 6. Deployment & DevOps
+
+### 6.1 Deployment Options
+
+**Kubernetes (Recommended):** Helm charts are provided for all components. Includes horizontal pod autoscaling, queue-based worker scaling with scale-to-zero, secrets management integration (HashiCorp Vault or Kubernetes secrets), TLS certificate management, and ingress routing.
+
+**Docker Compose:** Available for simpler deployments. Includes all components in a single configuration file. Requires NVIDIA Container Toolkit for GPU access.
+
+### 6.2 Air-Gapped Installation
+
+The platform is delivered as an offline installation bundle containing:
+
+- Pre-built container images (OCI archives, ~13 GB)
+- LLM model weights (50–150 GB depending on model selection)
+- OCR model files and language packs
+- Helm charts and/or Docker Compose configuration
+- Automated installation and validation script
+- Configuration templates with documented parameters
+
+Delivery via encrypted media, secure file transfer, or internal artifact repository.
+
+### 6.3 Upgrades
+
+Upgrades follow the same offline delivery model. Database schema migrations run automatically on startup. Kubernetes deployments support zero-downtime rolling updates with rollback capability.
+
+### 6.4 Monitoring & Observability
+
+| Capability | Implementation |
+|-----------|---------------|
+| Metrics & dashboards | Prometheus + Grafana (pre-configured) |
+| Log aggregation | Structured JSON logs; Fluentd/Fluentbit integration |
+| Alerting | Prometheus Alertmanager (configurable thresholds) |
+| Health checks | All services expose health and readiness probes |
+| Distributed tracing | OpenTelemetry (optional) |
+
+### 6.5 Backup & Recovery
+
+| Component | Method | RPO | RTO |
+|-----------|--------|-----|-----|
+| Database | pg_dump / WAL archiving | < 1 hour | < 1 hour |
+| Object Storage | Bucket replication | Configurable | < 2 hours |
+| Configuration | Version-controlled Helm values | N/A | < 30 min |
+
+---
+
+## 7. API Specifications & Security Model
+
+### 7.1 API Overview
+
+The platform exposes a RESTful API for all programmatic interactions:
+
+| Endpoint Group | Description | Authentication |
+|---------------|-------------|----------------|
+| `/api/auth/*` | SSO / LDAP authentication | Public (login flow) |
+| `/api/v1/documents/*` | Document upload, listing, retrieval | Session token |
+| `/api/v1/extractions/*` | Data extraction operations | Session token |
+| `/api/v1/chat/*` | AI-powered document interaction | Session token |
+| `/api/v1/organizations/*` | Organization management | Admin session token |
+| `/health` | Health and readiness | None |
+
+### 7.2 Authentication Flow
+
+Users authenticate via the customer's identity provider (SAML/OIDC) or LDAP. Upon successful authentication, an encrypted server-side session is created. Session tokens are stored as HTTP-only, Secure, SameSite cookies and validated on each request.
+
+For machine-to-machine integrations, the API supports organization-scoped API keys. Keys are SHA-256 hashed before storage and can be rotated without downtime.
+
+### 7.3 Security Controls
+
+| Control | Implementation |
+|---------|---------------|
+| Transport | HTTPS only (TLS 1.2+) |
+| Authentication | Session-based (HTTP-only cookies) or API keys |
+| Authorization | Role-based access control (RBAC), organization-scoped |
+| Input validation | Schema validation on all inputs |
+| Rate limiting | Configurable per-endpoint |
+| CORS | Configurable (default: same-origin) |
+| CSRF protection | Double-submit cookie |
+| Security headers | CSP, HSTS, X-Frame-Options |
+
+---
+
+## 8. SDK & Integration Details
+
+### 8.1 Embeddable Widget
+
+A JavaScript widget is available for embedding Sea.dev functionality into existing internal applications:
+
+| Feature | Details |
+|---------|---------|
+| Integration methods | `<script>` tag (standalone) or npm package (React) |
+| Bundle size | < 200 KB gzipped |
+| Browser compatibility | Chrome 90+, Firefox 90+, Safari 15+, Edge 90+ |
+| Customization | Theming via CSS custom properties; configurable branding |
+| Performance | < 1s load time (cached) |
+
+### 8.2 MCP Server
+
+An MCP (Model Context Protocol) server is available for integration with AI assistants and external tooling, enabling programmatic access to the platform's extraction and document capabilities.
+
+### 8.3 Performance Targets
+
+| Metric | Target |
+|--------|--------|
+| Widget load | < 1s (cached) |
+| API response (p95) | < 500ms |
+| Concurrent document uploads | 10+ |
+| Extraction throughput | GPU-dependent (see Section 5) |
+
+---
+
+## 9. Migration Considerations
+
+### 9.1 LLM Quality
+
+Self-hosted open-source models (70B parameter class) provide strong performance across extraction and chat tasks. Prompt tuning and comparative evaluation are conducted during onboarding to ensure output quality meets requirements for the customer's specific document types.
+
+### 9.2 OCR Accuracy
+
+The self-hosted OCR pipeline handles standard document formats well. For specialized financial documents (bank statements, invoices with complex layouts), we recommend providing sample documents during onboarding for accuracy benchmarking and configuration tuning.
+
+### 9.3 Model Updates
+
+On-premises models are updated via the same offline delivery mechanism used for platform upgrades. A model update cadence is agreed upon as part of the support arrangement.
+
+### 9.4 Ongoing Support
+
+The deployment includes installation support, operational runbooks, pre-configured monitoring dashboards, and a defined escalation path to minimize operational burden on the customer's infrastructure team.
+
+---
+
+## Appendix A: Deployment Checklist
+
+1. Provision servers per Section 1 specifications
+2. Install container runtime (Docker or Kubernetes)
+3. Install NVIDIA drivers and Container Toolkit on GPU nodes
+4. Load container images from offline archive
+5. Configure database and object storage
+6. Deploy LLM model weights to GPU nodes
+7. Configure environment variables and secrets
+8. Configure SSO/LDAP integration with identity provider
+9. Provision TLS certificates
+10. Deploy via Helm or Docker Compose
+11. Validate deployment via health checks and smoke tests
+12. Configure monitoring and alerting
+13. Configure backup schedules
+14. Conduct user acceptance testing