Technical System Architecture: Tasklight (SaaS task-management platform)

Owner: Platform team Status: Reviewed Last reviewed: 2 June 2026 Related documents: Tasklight Data Model, Tasklight Integration Spec, Tasklight Deployment Plan

---

1. Overview and goals

Tasklight is a multi-tenant, web-based task-management platform. Teams sign up, create workspaces, and manage projects and tasks in real time across web and mobile browsers. The architecture is optimised, in order, for availability (teams plan their day in it), maintainability (a small team owns it), and cost-efficiency at startup scale.

• Primary goal: keep the app responsive (under 300ms median API response) for tenants of up to 500 users.
• Quality goals (priority order): availability, maintainability, cost-efficiency.
• Explicit non-goals: offline-first sync and on-premise deployment are out of scope for this release.

2. Context and system boundary

Tasklight is a single product that sits between its users and a small set of external services. Users — team members and workspace admins — reach it through a browser. The system depends on a managed email provider to send invitations and notifications, a payment provider to handle subscriptions, and an object store for file attachments. A webhook endpoint lets the payment provider notify Tasklight of subscription changes. Single sign-on providers are an upstream dependency for tenants that enable SSO.

• Users / actors: team members, workspace admins, billing owners.
• Upstream dependencies: transactional email provider, payment provider, SSO identity providers.
• Downstream consumers: none yet; a public API for integrations is planned for a later release.
• Out of scope: the marketing website and the internal analytics warehouse.

3. Components

Component	Responsibility	Tech
Web client	Renders the single-page app and holds session state in the browser	TypeScript, React
API service	Stateless HTTP API: authentication, authorisation, all business logic	Node.js, Fastify
Realtime service	Pushes live task updates to connected clients over websockets	Node.js, WebSocket
Primary database	Source of truth for tenants, users, projects, tasks	PostgreSQL
Cache	Sessions and hot reads to keep the database off the critical path	Redis
Background worker	Sends emails, processes webhooks, runs scheduled cleanups	Node.js
Job queue	Decouples slow work from the request path	Redis-backed queue
Object store	Stores task file attachments	Managed object storage

4. Key data flows

Flow A — a user creates a task:

1. The user submits the task form in the web client, which sends an authenticated HTTPS request to the API service with a session token.
2. The API service validates the session against the cache, checks the user is authorised for the target project, and validates the payload.
3. The API service writes the new task to the primary database inside a transaction and invalidates the relevant cached project read.
4. The API service publishes a "task created" event to the realtime service, which pushes the update to every other client currently viewing that project, and returns the created task to the original caller.

Flow B — a user attaches a file and is notified:

1. The web client requests a short-lived upload URL from the API service and uploads the file directly to the object store, keeping large payloads off the API service.
2. The API service records the attachment metadata against the task in the database and enqueues a notification job on the job queue.
3. The background worker consumes the job, renders the notification, and asks the email provider to deliver it; the worker retries with backoff if the provider is briefly unavailable.

5. Technology choices and rationale

• API framework: chose Fastify over a heavier framework because the API is the throughput-critical path and Fastify's low per-request overhead supports the response-time goal with fewer instances.
• Primary database: chose PostgreSQL over a document store because tasks, projects, and tenants are highly relational and the team values transactional integrity and mature tooling over schema flexibility.
• Single language (TypeScript/Node across client, API, and worker): chose one language over a polyglot stack to keep a small team productive and let code and types be shared — a maintainability decision.
• Managed object storage for attachments: chose a managed store over storing files in the database to keep the database small and let clients upload directly, reducing API load.

6. Scalability and reliability

Scalability

• The API service and realtime service are stateless and scale horizontally behind a load balancer; sessions live in the cache, not in process memory, so any instance can serve any request.
• The primary database is the known bottleneck. The first scaling step is a read replica for reporting-style reads; sharding by tenant is the documented next step but is not implemented yet.

Reliability

• Failure handling: every external call (email, payment, object store) has a timeout and bounded retries; task creation is idempotent on a client-supplied key so a retried request cannot create duplicates.
• Redundancy: the API, realtime, and worker tiers run at least two instances each across availability zones; the database runs with an automatically promoted standby.
• Degradation: if the email provider is down, notification jobs queue and retry rather than blocking task creation — the core product stays usable.
• Targets: 99.9% monthly availability for the API; detailed recovery objectives live in the deployment and disaster-recovery plans.

7. Security

• Authentication: users authenticate with email and password or via their tenant's SSO provider; the API issues a session token stored as an HTTP-only cookie.
• Authorisation: every request is checked against the user's role within the target workspace; tenants are isolated at the data layer by a mandatory tenant ID on every query.
• Secrets and data: application secrets are injected from the platform secret manager, never committed; data is encrypted in transit (TLS) and at rest, and attachments use short-lived, scoped upload and download URLs.
• Trust boundaries: the API service treats everything from the client as untrusted and validates all input at the boundary before it reaches business logic.

8. Key risks and trade-offs

Decision	What it buys	What it costs	Mitigation
Single shared PostgreSQL for all tenants	Simplicity and low cost at current scale	A noisy tenant can affect others; it is the scaling ceiling	Per-tenant rate limits now; read replica then sharding documented as next steps
Stateless services with sessions in Redis	Easy horizontal scaling	Redis becomes a critical dependency	Redis runs replicated; the API falls back to validating tokens against the database if the cache is unavailable
Direct client uploads to object storage	Keeps large files off the API tier	More moving parts in the upload flow	Short-lived signed URLs and server-side validation of recorded metadata