# Product ## Platform web ## Users The primary users are organizations that run Twenty CRM and the administrators who configure secure, client-facing access to selected CRM data and workflows. Invited clients are the second core audience. They use the portal to view and, when permitted, contribute to the records, reports, files, and activity shared with them without entering the organization’s internal CRM workspace. ## Product Purpose Twenty CRM Client Portal provides a controlled workspace between an organization’s Twenty CRM and its clients. It lets administrators publish scoped record views, invite users, assign permissions, configure client-facing workflows, and monitor activity while Twenty remains the system of record. Success means clients can understand and act on the information shared with them, administrators can manage that access without exposing the internal workspace, and every request continues to respect the configured authorization boundary. ## Positioning The product is a self-hosted, metadata-driven client portal layer for Twenty CRM. Its distinguishing mechanism is that it turns Twenty metadata into configurable client workspaces while enforcing record scope and permissions on the server, without exposing the organization’s CRM credentials or internal workspace. ## Operating Context - Administrators connect a Twenty workspace, configure portal views from synchronized object metadata, define record scope and fixed filters, select visible or editable fields, and assign access. - Administrators invite users and manage client accounts, roles, portal assignments, authentication options, application branding, email delivery, audit history, and system health. - Invited users authenticate into one or more assigned portal views. Depending on their role and each view’s configuration, they can browse, filter, sort, save, export, create, or update scoped records and use related notes, attachments, dashboards, and reports. - Twenty remains the source of record data. The portal stores authentication, access, configuration, synchronized metadata, audit events, and webhook receipts in PostgreSQL. - Production deployments are self-hosted, commonly through Docker Compose, with a restricted Twenty API key and optional SMTP and OAuth/OpenID Connect integrations. ## Capabilities and Constraints - Access is invite-only and uses administrator, viewer, and contributor roles, with view-specific assignments and permissions. - Record access supports all matching records, authenticated Person scope, or an explicit record allowlist, plus administrator-configured fixed filters. - Interfaces are generated from Twenty metadata for tables, record details, filters, create and edit forms, select options, and validation. - Client workflows include record tables and detail panels, bulk updates, favorites, saved views, notes, attachments, configurable dashboards, secure embedded reports, and CSV, XLSX, and PDF exports. - Authentication supports credentials, Google, and a configurable OAuth/OpenID Connect provider while remaining invite-only. - Tenant branding can configure the product name, logo, login artwork, colors, portal copy, invitation email, and user avatars. - Twenty credentials and other integration secrets remain server-side. Record reads, mutations, and exports must reconstruct authorization and scope rather than trusting browser state. - Signed, deduplicated webhooks synchronize metadata changes. Audit logging, health checks, rate limits, metadata validation, and hardened non-root containers support production operation. - The application targets Node.js 22, Next.js 16, PostgreSQL 17, and modern web browsers. It is licensed under GPL-3.0. - Customer claims, pricing, benchmarks, deployment scale, and commercial support terms are undecided and must not be invented. ## Brand Commitments - The product name is **Twenty CRM Client Portal**. - The product should speak clearly and precisely about access, permissions, records, and security. It should avoid vague promises or claims unsupported by repository evidence. - Organization-specific branding is a product capability. Tenant identity should be expressible without weakening the portal’s accessibility or security boundaries. ## Evidence on Hand - [`README.md`](README.md) contains the current product narrative, feature inventory, architecture, setup guidance, and security model. - [`SECURITY.md`](SECURITY.md) documents supported release lines and the private vulnerability-reporting process. - [`CHANGELOG.md`](CHANGELOG.md) and [`RELEASING.md`](RELEASING.md) provide release history and operating evidence. - [`public/screenshots/`](public/screenshots/) contains current product screenshots for authentication, client and administrator dashboards, record workspaces, reports, and portal configuration. - [`scripts/seed-demo.ts`](scripts/seed-demo.ts) and the demo integration under [`src/lib/demo/`](src/lib/demo/) provide repeatable local evaluation data without a Twenty instance. - The repository contains automated unit, component, integration, and end-to-end tests for access-sensitive workflows. - No customer testimonials, case studies, external benchmarks, pricing, or adoption claims are currently on hand; future work must not fabricate them. ## Product Principles 1. **Keep Twenty authoritative.** The portal is a controlled client-facing layer, not a competing system of record. 2. **Scope every interaction.** Reads, writes, exports, and reports must honor the authenticated user, assigned portal view, configured record scope, filters, fields, and role. 3. **Make access understandable.** Administrators should be able to see and control what each client can reach; clients should see only relevant work and clear available actions. 4. **Preserve self-hosted control.** Organizations retain control of deployment, credentials, data boundaries, integrations, and tenant identity. 5. **Earn trust through operational clarity.** Security-sensitive states, metadata drift, delivery failures, and system health should be explicit and actionable.