System Architecture¶
System architecture describes how PotatoLabs products are composed from services, data stores, and operational components.
Service boundaries¶
Each service must have a clear responsibility, owner, and interface.
Services should not share implementation details across boundaries.
Communication and API boundaries¶
Preferred communication patterns are:
- Synchronous HTTP APIs for user-facing and operational requests
- Internal service calls only when the boundary is stable and documented
- Asynchronous work queues or background jobs when the operation does not need an immediate response
Any public or internal API must document:
- Purpose
- Authenticated callers
- Request and response shape
- Failure behavior
- Versioning or compatibility expectations
Data and storage architecture¶
- PostgreSQL is the primary relational datastore when a product needs durable structured data
- Redis is used for cache, coordination, rate limiting, sessions, or other short-lived state when appropriate
- Product data stores are owned by the service that uses them
- Shared schemas or cross-product writes are avoided unless explicitly approved
System composition¶
A product system may include application services, background workers, scheduled tasks, databases, caches, reverse proxies, and observability integrations.
The composition must be documented in the product's architecture and deployment pages.
Lifecycle alignment¶
System architecture must support the product lifecycle from development through validation, build, release, deployment, and monitoring.