Core Principles
The guiding principles behind RawStack's design decisions.
CQRS + Domain-Driven Design
The API separates reads from writes using the Command Query Responsibility Segregation pattern, implemented with NestJS CQRS. Business logic lives in the domain layer, isolated from infrastructure concerns.
- Commands handle writes (create user, create token)
- Queries handle reads (get token, list users)
- Sagas coordinate async operations between aggregates via the event bus
- Repositories abstract all data access behind interfaces
This keeps the codebase testable, predictable, and easy to extend.
Infrastructure as Code
The entire cloud environment is defined in TypeScript with AWS CDK. Infrastructure lives alongside the application code so changes are version-controlled, reviewable, and repeatable across environments.
Containerisation first
Every server-side component ships as a Docker image with a multi-stage build. Images are pushed to ECR and deployed to ECS Fargate — no SSH, no manual provisioning.
Auto-generated API client
The shared @rawstack/api-client package is generated from the API's OpenAPI spec. All frontends use the same typed client, eliminating hand-written API calls and keeping types in sync across the monorepo.
Type safety end-to-end
TypeScript is used across every JavaScript layer (web, admin, app, notification, infrastructure). The API uses Zod for runtime validation at the boundary. Together they catch mismatches at build time rather than in production.
Thin frontends
Frontends contain no business logic. They fetch data via React Query, validate forms with Zod + React Hook Form, and render with Radix UI primitives and Tailwind CSS. State management is kept close to the component that needs it.
Secrets out of code
Sensitive values (JWT secrets, DB passwords, API keys) are never committed. Each component ships an .env.dist / .env.example template. In production, secrets are injected at runtime via AWS Secrets Manager or environment variables.
@todo: architecture: probs needs an in dept discussion of DDD somewhere @todo: section on frontend light theming and separation of UI. front end web is shadui etc etc