ARCHITECTURE.md for coding agents: a template and how to use it

<!-- skeletiq:brief:start project=9bd3b18c-a31f-4faf-9a01-eaec4fed0447 version=2 released=true generated=2026-09-30T07:17:14.459802+00:00
     Managed by SkeletIQ. A refresh replaces this whole block, opening fence to closing
     fence — never append a second one, and edit the design rather than this text.
     Refresh with the SkeletIQ MCP server: get_design(mode="brief").
-->
# Multi-Tenant SaaS API for Team Task Management

*Version 2 · 30 September 2026*

## Overview

A SaaS platform providing task management for multiple tenant organizations with isolated data, supporting web and mobile clients via a unified API, leveraging SSO for authentication, and background processing for notifications.

## Components

| Name | Type | Technology | Description |
|------|------|------------|-------------|
| Web and Mobile Clients | external | — | End users accessing the system through web browsers and mobile applications; initiates all user requests. |
| API Gateway | gateway | AWS API Gateway | Single entry point for all client requests; handles routing, authentication token validation via SSO, rate limiting, and load balancing; terminates client connections. |
| Authentication Service (SSO) | external | — | Third-party SSO provider responsible for user authentication and authorization, issuing identity tokens used by the API Gateway. |
| Task API Service | service | Node.js with Express | Handles business logic for task management including CRUD operations, task assignment, deadlines, reminders, categorization, completion tracking, and multi-tenant user management; enforces tenant isolation and access control; exposes RESTful API endpoints for clients. |
| PostgreSQL Database | database | Amazon RDS PostgreSQL 14 | Stores all tenant data including tasks, users, teams, and metadata; enforces tenant isolation via row-level security on tenant_id; single shared database instance for operational simplicity and consistency. |
| Cache Layer | cache | Amazon ElastiCache Redis 7 | Caches frequently accessed task and user data to reduce database load and improve API response latency; cache entries are invalidated on writes to maintain consistency. |
| Message Queue | queue | Amazon SQS | Queues background jobs such as sending notifications for task updates and deadlines to decouple notification processing from API request handling, improving throughput and responsiveness. |
| Notification Worker Service | service | Node.js Worker | Consumes notification jobs from the message queue and sends notifications via email or in-app messaging; isolates background processing from API service to avoid impacting latency. |
| Email Delivery Service | external | — | Third-party email provider used for sending email notifications triggered by the notification worker. |
| Audit Log Service | service | Node.js with Elasticsearch | Records immutable audit logs of all access to tenant data for compliance and security monitoring; does not process or serve tenant data directly. |
| Monitoring and Alerting Service | service | Prometheus + Grafana + Alertmanager | Collects metrics and logs from all system components, monitors system performance and security, and triggers alerts on anomalies or threshold breaches; does not handle user or tenant data directly. |

## Connections

| Caller | Callee | Protocol | Notes |
|--------|--------|----------|-------|
| Web and Mobile Clients | API Gateway | HTTPS | send API requests |
| API Gateway | Authentication Service (SSO) | OAuth2/OIDC over HTTPS | validate SSO tokens |
| API Gateway | Task API Service | HTTPS REST | forward authenticated API requests |
| Task API Service | Cache Layer | TLS-encrypted Redis | read cache for tasks and users |
| Task API Service | PostgreSQL Database | PostgreSQL protocol over TLS | read/write tenant data |
| Task API Service | Message Queue | HTTPS REST | enqueue notification jobs |
| Notification Worker Service | Message Queue | HTTPS REST | consume notification jobs |
| Notification Worker Service | Email Delivery Service | SMTP/HTTPS API | send email notifications |
| Task API Service | Audit Log Service | HTTPS REST | log tenant data access events |
| API Gateway | Monitoring and Alerting Service | HTTPS | send metrics and logs |
| Task API Service | Monitoring and Alerting Service | HTTPS | send metrics and logs |
| Notification Worker Service | Monitoring and Alerting Service | HTTPS | send metrics and logs |

## Design Decisions

• All connections carrying user or tenant data use TLS or HTTPS to ensure data confidentiality and integrity in transit.

• An audit log service is added to record all accesses to tenant data for compliance and security monitoring.

• A monitoring and alerting service is introduced to track system performance and security, collecting metrics and logs from all components.

• Use a monolithic API service to simplify deployment and maintain tenant isolation via row-level security in a single PostgreSQL database.

• Employ an API Gateway that handles SSO token validation and rate limiting to centralize authentication and improve security.

• Use cache-aside pattern with Redis to improve read latency and reduce load on the database for frequently accessed data.

• Implement background notification processing via a message queue and worker service to decouple notification delivery from synchronous API calls.

• Rely on a third-party SSO provider for authentication to leverage standardized, secure identity management.

## Trade-offs

- Adding audit logging and monitoring increases operational complexity and resource usage but is necessary for compliance and security visibility.
- Using TLS on all user and tenant data connections adds slight latency but is essential for data protection.
- Maintaining a single database with row-level security simplifies deployment but may limit scalability compared to multi-tenant isolation strategies like schema-per-tenant.
- Asynchronous notification processing improves API responsiveness but introduces eventual consistency in notification delivery.
- Choosing a monolithic API service simplifies deployment and tenant data consistency but limits independent scaling of components.
- Using a single shared database with row-level security reduces operational complexity but risks cross-tenant data exposure if misconfigured.
- Employing a cache-aside pattern improves latency but introduces potential stale reads until cache invalidation.
- Background jobs via message queue improve API responsiveness but add complexity and eventual consistency for notifications.
- Relying on a third-party SSO provider offloads identity management but introduces dependency and potential single point of failure.

## Scalability Notes

The design uses a single PostgreSQL instance with row-level security suitable for a small scale SaaS with up to 50 sustained RPS and peaks around 100 RPS. The cache layer and message queue help offload read and background processing load respectively. Monitoring and audit logging are added with minimal impact on core request path. The system can scale vertically initially, with options to shard or add read replicas if needed in future.

## Requirements

### Targets

Build against these. Anything reading “not stated” was never given a number — ask rather than choosing one. The non-functional rows in the table below are the rest of the targets; they are not repeated here.

- **Users:** not stated
- **Data volume:** not stated
- **Growth:** not stated
- **Scale tier:** small
- **Reachable from:** the public internet
- **Sustained load:** about 50 requests a second
- **Read/write split:** 80% reads — No read/write split stated, so this design is described as 80% reads and 20% writes — assumed · typical for this kind of system. Say yours if it is different.
- **Peak over sustained:** 2x — No traffic shape stated, so headroom is sized for a 2x burst over the sustained rate. A steadier or spikier system needs a different figure.
- **Concurrent users:** 25 — Nobody stated a concurrency figure. 25 is 50 requests a second at a ratio that is assumed · typical for this kind of system; change the rate to change it.
- **Monthly budget:** not stated

| ID | Kind | Requirement | Source | Verdict | Why |
|----|------|-------------|--------|---------|-----|
| R1 | functional | User authentication and authorization via SSO | You set this | Passes (review rules) | The review looked for an authentication and authorization layer and raised nothing. |
| R2 | functional | Create, read, update, and delete tasks | Read from your prompt | No gap found (what cites it) | Cited by 2 components and 1 decision; nothing measured that it behaves as asked. |
| R3 | functional | Assign tasks to team members | Read from your prompt | No gap found (what cites it) | Cited by 1 component; nothing measured that it behaves as asked. |
| R4 | functional | Set task deadlines and reminders | Read from your prompt | No gap found (what cites it) | Cited by 1 component; nothing measured that it behaves as asked. |
| R5 | functional | Categorize tasks by project or team | Read from your prompt | No gap found (what cites it) | Cited by 1 component; nothing measured that it behaves as asked. |
| R6 | functional | Track task completion status | Read from your prompt | No gap found (what cites it) | Cited by 1 component; nothing measured that it behaves as asked. |
| R7 | functional | Send notifications for task updates and deadlines | Read from your prompt | No gap found (what cites it) | Cited by 3 components and 1 decision; nothing measured that it behaves as asked. |
| R8 | functional | Support for multiple teams within a single tenant | Read from your prompt | No gap found (what cites it) | Cited by 2 components and 1 decision; nothing measured that it behaves as asked. |
| R9 | functional | API endpoints for web and mobile clients | You set this | No gap found (what cites it) | Cited by 2 components and 1 decision; nothing measured that it behaves as asked. |
| R10 | functional | User management for team members | Read from your prompt | No gap found (what cites it) | Cited by 1 component; nothing measured that it behaves as asked. |
| R11 | non-functional | Latency should be under 200ms for API responses | You set this | No gap found (what cites it) | Cited by 2 components and 2 decisions; nothing measured that it behaves as asked. |
| R12 | non-functional | Throughput of 50 requests per second sustained | You set this | Passes (capacity) | Sized for 4,875 requests a second against the 50 requests a second this asks for. |
| R13 | non-functional | Availability of 99.9% | Read from your prompt | Passes (review rules) | The review looked for redundancy and failover and raised nothing. |
| R14 | non-functional | Data consistency across multi-tenant architecture | Read from your prompt | No gap found (what cites it) | Cited by 2 components and 1 decision; nothing measured that it behaves as asked. |
| R15 | non-functional | Scalability to accommodate growth in users and requests | Read from your prompt | No gap found (what cites it) | Cited by 1 component and 2 decisions; nothing measured that it behaves as asked. |
| R16 | functional | Multi-tenant task management capabilities including CRUD operations for tasks, user management, and notifications. | Read from your prompt | No gap found (what cites it) | Cited by 4 components; nothing measured that it behaves as asked. |
| R17 | functional | Audit logging for access to tenant data. | Read from your prompt | No gap found (what cites it) | Cited by 2 components and 1 decision; nothing measured that it behaves as asked. |
| R18 | non-functional | All connections carrying user or tenant data must use TLS or HTTPS. | Read from your prompt | Passes (review rules) | The review looked for encryption in transit and raised nothing. |
| R19 | non-functional | System must support a sustained load of about 50 requests per second. | You set this | Passes (capacity) | Sized for 4,875 requests a second against the 50 requests a second this asks for. |
| R20 | non-functional | Monitoring and alerting must be implemented to track system performance and security. | Read from your prompt | No gap found (what cites it) | Cited by 4 components and 1 decision; nothing measured that it behaves as asked. |

Requirements with nothing built for them: 1 of 20. Nothing in this design is built for R12 — ask before assuming they are out of scope.

Decisions citing evidence: 3 of 8. Retrieved sources used: 3 of 6.

## Rules

Checked against: GDPR (usual for SaaS apps), SOC2 (usual for SaaS apps). You named no regime, so these are the frameworks SaaS apps are usually held to -- confirm them before building to them.

## Build Order

Build in this order. It follows the dependency graph — an arrow means the source calls the target, so the target is built first — and falls back to component type wherever the graph is silent, which is why data stores come first. The IDs are what the drift check and the design tools key on; quote them exactly.

| # | ID | Component | Technology | Depends on | Why here |
|---|----|-----------|------------|------------|----------|
| 1 | cache_layer | Cache Layer (read-through) | Amazon ElastiCache Redis 7 | — | Stateful foundation — everything above it needs somewhere to read and write. |
| 2 | postgres_db | PostgreSQL Database (primary) | Amazon RDS PostgreSQL 14 | — | Stateful foundation — everything above it needs somewhere to read and write. |
| 3 | message_queue | Message Queue (work-queue) | Amazon SQS | — | Decouples what follows; stand it up before its producers and consumers exist. |
| 4 | monitoring_service | Monitoring and Alerting Service | Prometheus + Grafana + Alertmanager | — | Business logic. Build it once the stores and queues it depends on are up. |
| 5 | audit_log_service | Audit Log Service (worker) | Node.js with Elasticsearch | — | Background worker — build it once what it calls is up. |
| 6 | task_api_service | Task API Service (api) | Node.js with Express | audit_log_service, cache_layer, message_queue, monitoring_service, postgres_db | Business logic. Build it once the stores and queues it depends on are up. |
| 7 | auth_service | Authentication Service (SSO) (third-party) | — | — | Outside your control — integrate or stub it, do not build it. |
| 8 | api_gateway | API Gateway (edge) | AWS API Gateway | auth_service, monitoring_service, task_api_service | Entry point — wire it last, when the services behind it can answer. |
| 9 | external_client | Web and Mobile Clients (client) | — | api_gateway | The caller, not something you build here — the boundary it defines. |
| 10 | email_service | Email Delivery Service (third-party) | — | — | Outside your control — integrate or stub it, do not build it. |
| 11 | notification_worker | Notification Worker Service (worker) | Node.js Worker | email_service, message_queue, monitoring_service | Background worker — it consumes the queue, so build that first. |

### What this repo covers

`check_drift` assumes this repo implements the whole design. If it implements only part of it, pass `covers` with just the ids you are responsible for — otherwise every component built somewhere else is reported as missing. Every id in this design:

```
cache_layer
postgres_db
message_queue
monitoring_service
audit_log_service
task_api_service
auth_service
api_gateway
external_client
email_service
notification_worker
```

## Open Gaps

These are unresolved. Ask — do not guess, and do not silently pick an answer and build on it. Where the design has a view it is quoted below the question; it is a starting point for that conversation, not a decision. Anything you decide here should go back into the design, not only into the code.

- Open question — Should in-app messaging notifications be handled synchronously or asynchronously?
  The design suggests: Handle in-app messaging notifications asynchronously to avoid impacting API latency.
  Options: Synchronously · Asynchronously
  If it goes the other way: Affects notification worker design and API response times.
- Open question — What is the expected peak request rate and concurrency beyond the sustained 50 RPS?
  The design suggests: Assume peak is approximately double sustained rate, i.e., 100 RPS.
  Options: Higher peak · Lower peak
  If it goes the other way: Impacts capacity planning and scaling decisions.
- Open question — No compliance regime, budget ceiling or latency target was stated. Which of them apply?
- Open question — This design was sized on a flat read/write default rather than on a figure for this workload, and the capacity simulation and the cost estimate both rest on it. Is this workload read-heavy, write-heavy or balanced?
- Open question — The peak here is a multiple of the scale tier rather than of this workload's own shape. Is traffic steady, or does it burst?

- Unconfirmed assumption — The system will handle up to 50 requests per second sustained, with an 80% read to 20% write ratio.
  The design suggests: Design and size components to handle 50 RPS sustained with read-heavy workload.
  Options: Higher sustained load · Lower sustained load
  If it goes the other way: Sizing of services, databases, and queues would change accordingly.
- Unconfirmed assumption — Notifications are sent via email and in-app messaging, with email handled by a third-party service.
  The design suggests: Continue using third-party email service for notifications.
  Options: In-house email service · Other third-party providers
  If it goes the other way: Notification worker and email service integration would change.
- Unconfirmed assumption — Tenant isolation is enforced by row-level security in a single shared PostgreSQL database.
  The design suggests: Maintain row-level security for tenant data isolation.
  Options: Schema per tenant · Database per tenant
  If it goes the other way: Database design and operational complexity would be affected.

## Design Critique

> Checked during generation; it met the minimum score first time, so no revision was needed. That describes this pass only: this is version 2, and the versions before it have their own history in the project.

- **Overall:** 98 / 100
- **Security:** 99
- **Performance:** 99
- **Resilience:** 100
- **Data:** 100

The overall architecture of the multi-tenant SaaS API for team task management demonstrates a solid foundation, particularly with the use of an API gateway for centralized authentication and routing, as well as the implementation of a cache layer that effectively reduces database load and enhances read latency. The asynchronous messaging pattern employed for communication between services is commendable, as it promotes decoupling and resilience. However, there are critical issues that need immediate attention to ensure the security, performance, and reliability of the system.

The most pressing concerns include the lack of centralized secrets management, absence of a Content Delivery Network (CDN), and the omission of a Web Application Firewall (WAF). The absence of centralized secrets management increases the risk of credential leaks, which can lead to unauthorized access and data breaches, thereby compromising tenant data isolation. Furthermore, the lack of a CDN results in higher latency for users in distant regions, negatively impacting user experience and potentially leading to customer dissatisfaction. Lastly, without a WAF, the system is vulnerable to common web application attacks, exposing it to significant security risks. These issues could have severe real-world implications, including data breaches, increased operational costs due to performance degradation, and potential legal ramifications from non-compliance with data protection regulations.

To address these concerns, it is recommended to implement a centralized secrets management solution, such as HashiCorp Vault or AWS Secrets Manager, to securely store and manage sensitive credentials across services. Introducing a CDN, like Cloudflare or AWS CloudFront, would significantly improve response times for users located far from the origin server. Additionally, deploying a WAF, such as AWS WAF or Cloudflare WAF, would provide essential protection against the OWASP Top 10 vulnerabilities, enhancing the overall security posture of the application. These improvements will not only mitigate the identified risks but also enhance the architecture's scalability and resilience, ultimately leading to a better user experience.

> No critical finding blocks handoff. Findings below critical are recommended fixes and do not block handoff.

| Severity | Finding | Impact | Remediation |
|----------|---------|--------|-------------|
| Low | No centralized secrets management for 4 services. Without it, credentials may be hardcoded or scattered in env vars, increasing the risk of credential leaks. | Security | Use HashiCorp Vault, AWS Secrets Manager, or GCP Secret Manager. Never store credentials in code or env files committed to git. Use dynamic secrets with short-lived credentials where possible. Rotate all secrets on a schedule (90 days max) and on any suspected compromise. This check clears on secrets-management words anywhere in the design's evidence: a component name, technology or description, a connection label or protocol, a design decision, or the scalability notes. |
| Low | No CDN detected for external-facing architecture. Users in distant regions experience higher latency and the origin server handles all traffic. | Latency | Deploy a CDN (CloudFront, Cloudflare, Fastly) for static assets. Consider API edge caching for read-heavy endpoints. Use cache-control headers to optimise CDN hit rates. |
| Info | External traffic reaches the system without a Web Application Firewall (WAF). WAF protects against OWASP Top 10 attacks (XSS, SQL injection, etc.). | Security | Add WAF protection via CloudFront+WAF, Cloudflare, or AWS Shield. Enable OWASP Core Rule Set (CRS). Configure IP reputation blocking. Enable bot management for login and checkout flows. Review WAF logs and tune rules to reduce false positives. This check clears on a component whose name or technology names a WAF — it does not read descriptions or design decisions, so saying you have one in prose will not clear it. |

> Advisory — reported, not scored. These come from a framework nobody named for this design, a domain it only partly belongs to, or a check too uncertain to count; none of them lowers the score or needs fixing before handoff.

| Severity | Finding | Impact | Remediation |
|----------|---------|--------|-------------|
| Info | 1 requirement no component or decision cites: R12 “Throughput of 50 requests per second sustained”. This is what holds the score to its traceability ceiling — address one, or say why it does not need a component. | — | — |

- Cache layer detected — reduces database load and improves read latency.
- Async messaging detected — enables decoupled, resilient communication.
- API gateway detected — centralises auth, rate limiting, and routing.
- Well-decomposed with 4 services — enables independent deployment and team ownership.

---

*Generated by SkeletIQ*
<!-- skeletiq:brief:end -->