Installation & Deployment Guides

1  Architecture Overview

[Web (React/TS)] → [API (Strapi)]
│
├─ DB:       PostgreSQL / MySQL
├─ Cache:    Redis
├─ Storage:  S3 / MinIO / OSS
├─ Workflow: BPMN 2.0 Engine
└─ AuthZ:    RBAC + ABAC + Audit

2  Requirements

• Linux x86_64 / ARM64
• Docker + Compose / Kubernetes
• PostgreSQL 14+
• Optional: Redis / MinIO / Nginx

3  Quick Start (Docker Compose)

git clone https://github.com/monzotechnology/zenflow-oa.git
cd zenflow-oa
cp .env.example .env
docker compose up -d

Create admin account:

curl -X POST http://localhost:1337/admin/auth/local/register \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@example.com","password":"ChangeMe!123"}'

Access the portal → https://zenflow.example.com

4  Reverse Proxy (Nginx)

server {
  listen 443 ssl http2;
  server_name zenflow.example.com;

  ssl_certificate     /etc/letsencrypt/live/zenflow/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/zenflow/privkey.pem;

  location / {
    proxy_pass http://web:8088;
  }
  location /api/ {
    proxy_pass http://api:1337/;
  }
}

5  Key Modules

• Organization & HR — employee profiles, contracts, onboarding flows
• Attendance & Leave — multi-method clock-in, leave tracking, appeals
• Payroll & Benefits — auto calculation, batch disbursement, cost analysis
• Performance & Training — goal setting, 360° feedback, analytics
• Administration & Projects — assets, budgets, tasks, collaboration
• Workflow & System — visual BPMN, conditions, notifications, audits

6  Integrations

• SSO — OIDC / SAML / LDAP (Azure AD, Google Workspace)
• Mail & IM — SMTP / Teams / Slack / Lark / Feishu
• Finance & ERP — REST / GraphQL / Webhooks
• Storage — S3 / MinIO / OSS

7  Monitoring & Backup

# Database backup
docker compose exec db pg_dump -U zenflow zenflow > backup.sql

# File backup
tar czf config_$(date +%F).tar.gz config/

Prometheus health endpoint: /api/health

8  Security & Compliance

• Role- and attribute-based access control (RBAC + ABAC)
• Full audit logging for login, workflow, and salary changes
• Data localization and field-level masking (PII / salary)
• Configurable retention policies and export restrictions

9  Common Issues

10  Vault CX + Zenflow OA Integration

• Unified SSO (IdP / SCIM) for shared users and roles
• OA organizational data used as Vault CX ABAC attributes
• Unified audit logging to Grafana / Loki
• Shared deployment cycle and version governance

11  Release Flow

• Feature branch → PR → CI/CD test → build image
• Tag vX.Y.Z → push to registry
• Run DB migration if needed
• Update changelog and Helm chart

12  FAQ

• Can it run offline? Yes, both products support air-gapped Docker images.
• Can OA and Vault CX share auth? Yes, via a central IdP (Keycloak / Azure AD).
• Is multilingual supported? Yes — EN / ZH / JA.
• RPO/RTO targets? RPO ≤ 15 min, RTO ≤ 30 min.

1  Architecture Overview

[Web (Next.js)] → [API (FastAPI)]
│
├─ Models:    Ollama / OpenAI / Anthropic / Local
├─ Vector DB: FAISS / Milvus / Chroma
├─ DB:        PostgreSQL (primary) + Redis (cache/queue)
├─ Storage:   S3 / MinIO / OSS
├─ Telemetry: Prometheus + Grafana
└─ Logs/Traces: Loki / ELK / OTLP

• Security: JWT + RBAC/ABAC, org-domain-project isolation, full audit trail.
• Governance: prompt versioning, SLO dashboards, feature flags, tool success-rate monitoring.
• Widgets: embeddable chat widgets via script or iframe with domain whitelist control.

2  Requirements

• Linux x86_64 / ARM64 (Ubuntu 22.04+ / RHEL 9+)
• Docker 24+ / Compose v2 or Kubernetes 1.26+
• PostgreSQL 14+, Redis 6+
• Optional: MinIO / Prometheus / Grafana / Loki
• Ports: 80 / 443 / 8080 / 3000 / 5432 / 6379

3  Quick Start (Docker Compose)

git clone https://github.com/monzotechnology/vaultcx.git
cd vaultcx
cp .env.example .env
docker compose up -d

Initialize admin:

docker compose exec api vxcctl admin create \
  --email admin@example.com --password "ChangeMe!123"

Then visit → https://vaultcx.example.com

4  Reverse Proxy + TLS (Nginx)

server {
  listen 443 ssl http2;
  server_name vaultcx.example.com;

  ssl_certificate     /etc/letsencrypt/live/vaultcx/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/vaultcx/privkey.pem;

  location / {
    proxy_pass http://web:3000;
  }
  location /api/ {
    proxy_pass http://api:8080/;
  }
}

5  Configuration Highlights

• Domains & Prompts — define YAML prompt files under /config/prompts.
• Feature Flags & Rate Limits — controlled in /config/app.yaml.
• Access Control — role-based (super-admin, editor, viewer) + ABAC for fine-grained policies.

6  Embed Widget

Add this script tag to any webpage to embed the Vault CX chat widget:

<script async
  src="https://vaultcx.example.com/embed/v1.js"
  data-wid="wid_xxxx"
  data-lang="en"
  data-theme="auto"
  data-position="bottom-right"></script>

7  Monitoring & SLO

• Exposes Prometheus metrics at /metrics
• Grafana dashboard → vaultcx-slo.json
• Key indicators: QPS, Latency P95, Tool Success Rate, Token Usage

8  Backup & Upgrade

# Backup database
docker compose exec db pg_dump -U vaultcx vaultcx > backup.sql

# Pull latest image and apply migrations
docker compose pull && docker compose up -d
docker compose exec api vxcctl migrate db

9  Troubleshooting