# Cloutal Workspace Architecture

Cloutal Workspace is planned as a standalone, multi-tenant subscription SaaS product. This index is planning-only: it does not describe implemented application code, installed dependencies, database migrations, deployment automation, or infrastructure configuration.

## Architecture status labels

Use these labels consistently in architecture documents:

- **Approved foundation** — already established by the repository documentation.
- **Recommended direction** — the preferred approach, subject to product-owner approval.
- **Deferred decision** — intentionally decided later.
- **Open question** — requires product-owner input.

## Approved foundations

- **Approved foundation** — Cloutal Workspace is a standalone product maintained in this repository only.
- **Approved foundation** — Future implementation must not depend on WordPress or on the existing `thelkstudio/Cloutal` production application, database, users, sessions, configuration, deployment, or source code.
- **Approved foundation** — MySQL is the planned primary relational database unless a later reviewed architecture decision changes it.
- **Approved foundation** — Organizations are the tenant boundary, and organization-scoped data must not be readable, writable, listable, searchable, exportable, downloadable, or inferable across organization boundaries.
- **Approved foundation** — Users are global accounts and may belong to multiple organizations through membership records. A user may have a different role in each organization. Authorization must always use trusted active-organization context and verify membership and permission server-side.
- **Approved foundation** — Configuration must be environment-based, safe placeholders must remain safe to commit, and UAT and production must keep secrets, databases, Stripe modes, sessions, encryption keys, and customer data separate.
- **Approved foundation** — Production deployment must be reviewed, auditable, environment-specific, and separated from local machines and unreviewed automation.

## Recommended architecture summary

- **Recommended direction** — Launch as a standalone PHP application using Laravel, organized as a modular monolith rather than microservices.
- **Recommended direction** — Use a shared application and shared MySQL database with strict organization-level tenant isolation.
- **Recommended direction** — Use Laravel Blade for a server-rendered responsive interface, with Livewire and lightweight JavaScript only where selective interactivity is useful.
- **Recommended direction** — Avoid requiring a separate frontend single-page application at launch.
- **Recommended direction** — Keep application servers stateless enough that additional identical servers can be added later.
- **Recommended direction** — Use background jobs for email, exports, billing events, retention, deletion, and maintenance.
- **Recommended direction** — Be Redis-ready for shared sessions, cache, and queues, while allowing initial local development without mandatory Redis.
- **Recommended direction** — Prepare customer-uploaded files for shared storage or object storage rather than relying permanently on one server filesystem.
- **Recommended direction** — Use Stripe-hosted Checkout, Stripe-hosted customer billing portal, and Stripe subscriptions so card data does not pass through or remain on Cloutal Workspace servers.
- **Recommended direction** — Use `https://uat.cloutal.com/workspace/` for initial UAT and `https://cloutal.com/workspace/` for initial production as a transitional deployment URL plan, with a planned future move to `https://workspace.cloutal.com/` and a possible future UAT-specific Workspace subdomain.
- **Recommended direction** — Do not hardcode `/workspace` into routes, links, assets, authentication callbacks, cookies, or application logic; environment-specific URLs must come from configuration so the same code can run under the temporary path and later under a dedicated subdomain.

## Supporting documents

- [Technical stack](TECH_STACK.md) covers framework, frontend, database, queueing, cache, storage, email, testing, monitoring, alternatives, and technologies not recommended at launch.
- [Data model](DATA_MODEL.md) describes planned entities, relationship boundaries, sensitive records, tenant scopes, and retention/deletion categories without final SQL or migrations.
- [Authentication, billing, and lifecycle](AUTH_BILLING_LIFECYCLE.md) explains signup, login, Google identity linking, Stripe subscription flows, trials, retention, deletion, and failure handling.
- [Security and tenancy](SECURITY_AND_TENANCY.md) documents authentication security, authorization, tenant isolation, sensitive-data handling, audit logging, file protection, testing, and incident readiness.
- [Deployment and scaling](DEPLOYMENT_AND_SCALING.md) documents local development, UAT, production, GitHub workflow, environment separation, backups, health checks, rollback, monitoring, and staged scaling.

## Deferred decision: customer-owned domain authentication handoff

- **Deferred decision** — Customer-owned domains such as `staff.customer.com` cannot share browser session cookies with an unrelated central Cloutal login domain. A future reviewed architecture decision must choose how authenticated users move between the central login domain and verified customer-owned domains.
- **Deferred decision** — Approaches to evaluate include central authentication followed by a short-lived, signed, single-use login handoff to the verified destination hostname, or independently established authenticated sessions on each customer domain.
- **Approved foundation** — Reusable session credentials must never be placed in query strings. Any handoff token must be short-lived, single-use, audience-bound to the intended hostname, and protected against replay.
- **Approved foundation** — The destination hostname must already be verified and mapped to the correct organization before a handoff or customer-domain session is established.
- **Approved foundation** — Session cookies must be Secure, HTTP-only, SameSite-aware, and scoped only to the appropriate hostname.
- **Recommended direction** — OAuth callbacks should remain centralized where practical to avoid per-customer callback sprawl.

## Open Questions

- **Open question** — What exact subscription plans and prices should be offered?
- **Open question** — Should billing be monthly, annual, or both?
- **Open question** — Are payment details required when starting a trial?
- **Open question** — What behavior is required during suspension?
- **Open question** — Is read-only access offered after trial expiration or payment failure?
- **Open question** — Which organization roles exist at launch beyond owner, editor, and regular user?
- **Open question** — What platform-administrator support-access rules and approval process are required?
- **Open question** — What audit-log retention period is required?
- **Open question** — What backup retention period is required?
- **Open question** — What initial customer-domain provider and certificate strategy should be used?
- **Open question** — What initial email provider should be used?
- **Open question** — What file-upload limits should apply by plan and file type?
- **Open question** — Is MFA mandatory for owners, editors, or platform administrators at launch?

## Deferred decisions

- **Deferred decision** — Exact Laravel, PHP, MySQL, Node, and package versions should be selected when the application is scaffolded.
- **Deferred decision** — Final database schema, indexes, and migrations should be designed when application data models are implemented.
- **Deferred decision** — Deployment automation details, provider-specific infrastructure, and GitHub Actions should be reviewed in a later implementation task.