Real architecture decision records

Analytics queries are becoming complex and DynamoDB makes aggregation difficult without expensive scan operations. The team spends significant time working around its limitations.

1. Continue with DynamoDB and build a query layer
2. Introduce Postgres for analytics workloads
3. Move to a managed data warehouse (Redshift, BigQuery)

Introduce Postgres as the analytics database while keeping DynamoDB for transactional workloads. The team has existing Postgres expertise and the data volume does not yet justify a full data warehouse.

Operational overhead increases (one more database to manage). Querying flexibility improves significantly. Risk of schema drift between transactional and analytics stores must be managed with an ETL process.

The current session-based auth stores tokens in cookies with insufficient rotation. A security audit flagged the implementation as vulnerable to CSRF and token theft. We need a modern auth approach that supports third-party integrations.

1. Patch the current cookie-based session system
2. Adopt OAuth 2.0 with Authorization Code + PKCE
3. Use a managed auth provider (Auth0, Clerk)

Implement OAuth 2.0 with Authorization Code + PKCE. This eliminates the CSRF risk, supports future third-party integrations, and keeps auth logic in-house rather than adding a paid vendor dependency.

Implementation complexity is higher than patching. The team needs to handle token refresh, revocation, and key rotation. Long-term this is the right architecture, but the migration has a ~3-week window risk.

Custom data fetching hooks have grown inconsistent across the app — some cache, some don't, loading and error states are handled differently everywhere, and there is no built-in way to invalidate stale data. This causes UX bugs and maintenance burden.

1. Standardise the custom hook pattern with a shared utility
2. Adopt TanStack Query (React Query)
3. Move to SWR for a lighter-weight option

Adopt TanStack Query v5 as the standard data-fetching layer. It provides caching, background refetching, optimistic updates, and consistent loading/error states out of the box. The API is stable, well-documented, and the ecosystem is large.

Adds a dependency and requires migrating existing hooks incrementally. SWR would have been lighter but lacks mutation handling and devtools. The migration can be done feature-by-feature over 4–6 weeks with no big-bang rewrite.

npm is causing hoisting conflicts between packages in the monorepo, resulting in phantom dependencies and inconsistent installs in CI. Install times have grown to 4+ minutes. We need a package manager designed for monorepo workspaces.

1. Stay on npm, add a `.npmrc` to disable hoisting
2. Migrate to pnpm with workspace support
3. Migrate to Yarn Berry with Plug'n'Play

Under review. Leaning toward pnpm — it uses hard links to avoid duplication, enforces strict dependency boundaries, and drops install time to under 90 seconds in benchmarks. Yarn Berry's PnP mode has known compatibility issues with some tooling.

Requires team onboarding and updating CI/CD scripts. All developers need pnpm installed globally. PnP compatibility issues are avoided, but pnpm's strict mode may surface phantom dependencies that were silently working before.

Request validation is ad-hoc — some endpoints validate manually, others trust the client. TypeScript types only enforce shape at compile time; runtime validation is missing. This led to two production incidents where malformed payloads caused 500 errors.

1. Write a shared validation utility using manual type guards
2. Adopt Zod for schema-based validation
3. Use Joi (established but no TypeScript-first design)

Adopt Zod as the standard validation library. Schemas are defined once and produce both runtime validation and inferred TypeScript types, eliminating the drift between types and validation logic. All new endpoints must define a Zod schema.

Bundle size increases by ~13 KB gzipped. Existing endpoints must be migrated progressively. The tradeoff is strongly in Zod's favour — the type inference alone eliminates an entire class of bugs.

Redis session storage adds an infra dependency and latency on every authenticated request. As traffic grows, the Redis cluster cost has become significant. We evaluated moving to stateless JWTs.

1. Keep Redis sessions with connection pooling
2. Move to short-lived JWTs (15 min) with refresh tokens

Move to short-lived JWTs with refresh tokens stored in HttpOnly cookies. Eliminates the Redis dependency for sessions. Access tokens expire quickly to limit exposure.

Token revocation becomes harder — a compromised access token is valid until expiry. Refresh token rotation mitigates but does not eliminate this. Accepted as a reasonable tradeoff at the time.