# Technical Stack

This document records recommended technical direction for Cloutal Workspace. It is planning-only and does not install frameworks, packages, dependencies, or tooling.

## Status labels

- **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.

## Recommended stack

| Area | Recommendation | Reason |
| --- | --- | --- |
| Backend framework | **Recommended direction** — Standalone PHP application using Laravel. | Laravel provides mature routing, middleware, validation, queues, sessions, mail, authentication primitives, testing support, migrations when application models are introduced, and an ecosystem suited to subscription SaaS. |
| Application architecture | **Recommended direction** — Modular monolith at launch. | Keeps product boundaries clear while avoiding microservice operational cost before the product needs it. Modules can separate billing, identity, organizations, files, auditing, and lifecycle concerns. |
| Frontend approach | **Recommended direction** — Server-rendered responsive UI using Laravel Blade, with Livewire and lightweight JavaScript where helpful. | Supports fast delivery and maintainability without requiring a separate frontend SPA at launch. Interactive areas can be enhanced selectively. |
| Database | **Approved foundation** — MySQL is the planned primary relational database. | A relational model fits users, organizations, memberships, subscriptions, audit events, retention records, and tenant-scoped business records. |
| Authentication | **Recommended direction** — Email/password, email verification, password resets, Google OAuth/OpenID Connect, secure sessions, rate limiting, logout from all devices, and MFA-ready architecture. | Covers standard SaaS access needs while allowing stronger controls for owners, editors, and platform administrators. Passwords must use secure one-way hashing and must never be reversibly encrypted. |
| Billing | **Recommended direction** — Stripe Checkout, Stripe customer billing portal, and Stripe subscriptions. | Stripe-hosted flows keep full card numbers and CVV data off Cloutal Workspace servers while supporting subscriptions, plan changes, cancellations, failed payments, and reactivation. |
| Queueing | **Recommended direction** — Background jobs for email, exports, billing events, retention, deletion, and maintenance. | Long-running or retryable work should not block web requests and must be idempotent. |
| Cache and sessions | **Recommended direction** — Redis-ready architecture, with local cache/session drivers acceptable for initial local development. | Local development stays simple, while UAT/production can move to shared sessions, cache, and queues as scaling requires. |
| File storage | **Recommended direction** — Shared filesystem or object-storage readiness for customer-uploaded files. | Files must remain available when servers are replaced or scaled horizontally and must be tenant-aware. |
| Email | **Recommended direction** — Use an environment-configured email provider for verification, password resets, invitations, trial reminders, billing notices, deletion warnings, and operational notifications. | Email behavior varies by environment and provider; credentials must remain outside source code. |
| Testing | **Recommended direction** — Automated feature, authorization, tenant-boundary, billing-webhook, lifecycle-job, and security regression tests. | Tests must prove Organization A cannot read, modify, list, search, export, download, or infer Organization B's information. |
| Monitoring | **Recommended direction** — Error monitoring, queue monitoring, failed-job tracking, backup-success monitoring, disk-space monitoring, custom-domain health checks, and security alerts. | Automation can retry and alert, but unusual failures, security incidents, restoration decisions, and customer disputes may still require human intervention. |

## Alternatives considered

- **Recommended direction** — Do not use microservices at launch. Microservices add distributed tracing, network failure handling, service deployment orchestration, and data-consistency complexity before the product requires it.
- **Recommended direction** — Do not require a separate frontend single-page application at launch. A SPA would add API surface area, authentication complexity, build tooling, and duplicated validation before there is a proven need.
- **Recommended direction** — Do not use multiple tenant databases at launch. A shared MySQL database with strict organization scoping is simpler to operate initially; tenant isolation must be enforced in application authorization, queries, jobs, caches, sessions, files, exports, and audit logs.
- **Recommended direction** — Do not make Redis mandatory for initial local development. The architecture should be Redis-ready, but local setup should remain approachable until shared infrastructure is required.
- **Recommended direction** — Do not introduce event-sourcing, CQRS, GraphQL, Kubernetes, or a search cluster at launch unless a later reviewed product requirement justifies them.

## Technologies not introduced at launch

- **Recommended direction** — No framework packages or Composer/JavaScript dependencies are added by this documentation task.
- **Recommended direction** — No deployment workflows, GitHub Actions, infrastructure configuration, SQL schemas, migrations, or application code are introduced by this documentation task.
- **Deferred decision** — Exact Laravel, PHP, MySQL, Node, Livewire, Stripe library, testing library, and monitoring package versions should be selected when the application is scaffolded.

## Open questions

- **Open question** — Which email provider should be used first?
- **Open question** — Which monitoring and alerting services should be used first?
- **Open question** — What file-upload size and type limits should be supported at launch?