From a373bfd117b6678ba7a07361442b2929a198a012 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Fri, 19 Jun 2026 12:05:24 +0000 Subject: [PATCH] docs: add Architecture Decision Records (ADRs) system - Created docs/adr/ directory - Added ADR-0001 to document the ADR process itself - Added ADRs 0002-0007 for existing architectural decisions (PostgreSQL, TypeORM, JWT, NestJS, Winston, Security/Validation) - Created docs/adr/README.md as an index for all ADRs - Updated CONTRIBUTING.md with the ADR process instructions Co-authored-by: gloskull <189399494+gloskull@users.noreply.github.com> --- CONTRIBUTING.md | 9 +++++ .../adr/0001-record-architecture-decisions.md | 33 +++++++++++++++++++ .../0002-postgresql-for-relational-data.md | 29 ++++++++++++++++ docs/adr/0003-typeorm-for-nest-integration.md | 30 +++++++++++++++++ docs/adr/0004-jwt-refresh-tokens-auth.md | 30 +++++++++++++++++ docs/adr/0005-nestjs-opinionated-framework.md | 31 +++++++++++++++++ docs/adr/0006-winston-structured-logging.md | 29 ++++++++++++++++ docs/adr/0007-security-validation-defaults.md | 32 ++++++++++++++++++ docs/adr/README.md | 17 ++++++++++ 9 files changed, 240 insertions(+) create mode 100644 docs/adr/0001-record-architecture-decisions.md create mode 100644 docs/adr/0002-postgresql-for-relational-data.md create mode 100644 docs/adr/0003-typeorm-for-nest-integration.md create mode 100644 docs/adr/0004-jwt-refresh-tokens-auth.md create mode 100644 docs/adr/0005-nestjs-opinionated-framework.md create mode 100644 docs/adr/0006-winston-structured-logging.md create mode 100644 docs/adr/0007-security-validation-defaults.md create mode 100644 docs/adr/README.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a81475f..dae14f6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -59,6 +59,15 @@ All new features should include unit tests. Aim for >85% coverage on service fil 5. Commit with a descriptive message 6. Push and create a pull request +## Architecture Decision Records (ADRs) + +We use ADRs to document important architectural decisions. These records are located in the `docs/adr/` directory. + +- **Process**: When making a significant architectural change, propose it via a new ADR. +- **Format**: Follow the [Michael Nygard format](https://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions). +- **Immutability**: Once an ADR is accepted, it is immutable. To change a decision, create a new ADR that supersedes the old one. +- **Naming**: Use `NNNN-short-title.md` (e.g., `0008-use-redis-for-caching.md`). + ## Project Structure ``` diff --git a/docs/adr/0001-record-architecture-decisions.md b/docs/adr/0001-record-architecture-decisions.md new file mode 100644 index 0000000..7a0281e --- /dev/null +++ b/docs/adr/0001-record-architecture-decisions.md @@ -0,0 +1,33 @@ +# 1. Record architecture decisions + +Date: 2025-05-14 + +## Status + +Accepted + +## Context + +We need to record the architectural decisions made for this project. + +## Decision + +We will use Architecture Decision Records (ADRs) to document our architectural decisions. +We will follow the format proposed by Michael Nygard. + +Each ADR will have: +- Title (NNNN-short-title.md) +- Date +- Status (Proposed, Accepted, Deprecated, Superseded) +- Context +- Decision +- Consequences (Positive and Negative) + +ADRs are immutable once Accepted. If a decision is changed, a new ADR will be created to supersede the old one. + +## Consequences + +- We will have a record of our architectural decisions. +- Future contributors will have context for the decisions made. +- We will be able to see the evolution of our architecture. +- There will be a small overhead in documenting each decision. diff --git a/docs/adr/0002-postgresql-for-relational-data.md b/docs/adr/0002-postgresql-for-relational-data.md new file mode 100644 index 0000000..92b0ffe --- /dev/null +++ b/docs/adr/0002-postgresql-for-relational-data.md @@ -0,0 +1,29 @@ +# 2. PostgreSQL for relational data + +Date: 2025-05-14 + +## Status + +Accepted + +## Context + +The platform handles tips and transactions which require high relational integrity and ACID compliance. We need a reliable database system to manage these records. + +## Decision + +We chose PostgreSQL over MongoDB. + +PostgreSQL is a powerful, open-source object-relational database system that provides strong consistency, complex queries, and robust relational integrity. + +## Consequences + +### Positive +- Ensures relational integrity for tips, users, and transactions. +- Provides ACID compliance for financial-related data. +- Excellent support for complex queries and indexing. +- Mature ecosystem and widespread developer familiarity. + +### Negative +- Schema migrations are required for changes. +- Scaling horizontally can be more complex than with some NoSQL databases. diff --git a/docs/adr/0003-typeorm-for-nest-integration.md b/docs/adr/0003-typeorm-for-nest-integration.md new file mode 100644 index 0000000..3aa8ee2 --- /dev/null +++ b/docs/adr/0003-typeorm-for-nest-integration.md @@ -0,0 +1,30 @@ +# 3. TypeORM for NestJS integration + +Date: 2025-05-14 + +## Status + +Accepted + +## Context + +We need an Object-Relational Mapper (ORM) to interact with our PostgreSQL database. The project is built using TypeScript and NestJS. + +## Decision + +We chose TypeORM over Prisma. + +TypeORM is a TypeScript-first ORM that integrates natively with NestJS through `@nestjs/typeorm`. It supports the Data Mapper and ActiveRecord patterns, fitting well with NestJS's architectural style. + +## Consequences + +### Positive +- Native and mature integration with NestJS. +- Excellent TypeScript support and decorators. +- Support for multiple database systems if needed in the future. +- Large community and extensive documentation. + +### Negative +- Some complex queries might be harder to express than in raw SQL. +- Performance overhead compared to raw SQL or more lightweight libraries. +- Some might find its API more verbose compared to Prisma. diff --git a/docs/adr/0004-jwt-refresh-tokens-auth.md b/docs/adr/0004-jwt-refresh-tokens-auth.md new file mode 100644 index 0000000..fd3d1c7 --- /dev/null +++ b/docs/adr/0004-jwt-refresh-tokens-auth.md @@ -0,0 +1,30 @@ +# 4. JWT with refresh tokens for authentication + +Date: 2025-05-14 + +## Status + +Accepted + +## Context + +We need a secure way to authenticate users and maintain their sessions. + +## Decision + +We chose JWT with refresh tokens over traditional session-based authentication. + +JWTs allow for stateless authentication, which is easier to scale and works well for APIs. Refresh tokens provide a way to maintain user sessions without requiring frequent re-authentication while keeping access token lifetimes short for security. + +## Consequences + +### Positive +- Stateless and scalable. +- Works well across different domains and mobile apps. +- Short-lived access tokens improve security. +- Refresh tokens allow for seamless UX by renewing access tokens in the background. + +### Negative +- Complexity in managing token rotation and revocation. +- Tokens cannot be easily invalidated before they expire (unless using a blacklist). +- Requires secure storage for refresh tokens (e.g., in the database). diff --git a/docs/adr/0005-nestjs-opinionated-framework.md b/docs/adr/0005-nestjs-opinionated-framework.md new file mode 100644 index 0000000..7abf044 --- /dev/null +++ b/docs/adr/0005-nestjs-opinionated-framework.md @@ -0,0 +1,31 @@ +# 5. NestJS as the primary framework + +Date: 2025-05-14 + +## Status + +Accepted + +## Context + +We need a backend framework to build our API. + +## Decision + +We chose NestJS over Express. + +NestJS provides an opinionated structure, built-in Dependency Injection (DI), and excellent TypeScript support out of the box. It is built on top of Express (by default) but adds a layer of abstraction that promotes modularity and maintainability. + +## Consequences + +### Positive +- Consistent and opinionated project structure. +- Built-in support for Dependency Injection and modularity. +- Strong TypeScript integration. +- Large ecosystem of official and community modules. +- Easier to scale for larger teams and complex codebases. + +### Negative +- Steeper learning curve compared to Express. +- More boilerplate code for simple features. +- Heavier framework compared to minimal alternatives. diff --git a/docs/adr/0006-winston-structured-logging.md b/docs/adr/0006-winston-structured-logging.md new file mode 100644 index 0000000..fba1d05 --- /dev/null +++ b/docs/adr/0006-winston-structured-logging.md @@ -0,0 +1,29 @@ +# 6. Winston for structured logging + +Date: 2025-05-14 + +## Status + +Accepted + +## Context + +We need a robust logging system to monitor the application and debug issues. + +## Decision + +We chose Winston over Pino. + +Winston is a versatile and mature logging library with a large number of transports. It has excellent integration with NestJS through `nest-winston`, allowing us to easily replace the default NestJS logger with a structured, multi-transport logging system. + +## Consequences + +### Positive +- Mature and widely used in the Node.js ecosystem. +- Supports multiple transports (console, file, HTTP, etc.). +- Easy integration with NestJS via `nest-winston`. +- Highly configurable log formats. + +### Negative +- Slower than Pino (though usually not a bottleneck for most applications). +- API can be seen as more complex than simpler logging libraries. diff --git a/docs/adr/0007-security-validation-defaults.md b/docs/adr/0007-security-validation-defaults.md new file mode 100644 index 0000000..b9604c6 --- /dev/null +++ b/docs/adr/0007-security-validation-defaults.md @@ -0,0 +1,32 @@ +# 7. Security and validation defaults + +Date: 2025-05-14 + +## Status + +Accepted + +## Context + +We need to ensure our API is secure and handles request data validation consistently. + +## Decision + +We chose to use Helmet, Compression, and class-validator as our security and validation defaults. + +- **Helmet**: Helps secure the app by setting various HTTP headers. +- **Compression**: Reduces the size of the response body, improving performance. +- **class-validator / class-transformer**: Provides a declarative way to validate and transform request data using decorators on DTOs. + +## Consequences + +### Positive +- Improved security through standard HTTP headers. +- Better performance with response compression. +- Consistent and robust data validation using NestJS `ValidationPipe`. +- Reduced boilerplate for input validation. + +### Negative +- Helmet may require configuration for certain features (like CSP). +- Compression adds some CPU overhead. +- Decorator-based validation can sometimes lead to large DTO files. diff --git a/docs/adr/README.md b/docs/adr/README.md new file mode 100644 index 0000000..38bab3f --- /dev/null +++ b/docs/adr/README.md @@ -0,0 +1,17 @@ +# Architecture Decision Records (ADRs) + +This directory contains the Architecture Decision Records for the StellarTip Backend project. + +## Index + +- [0001 - Record architecture decisions](0001-record-architecture-decisions.md) +- [0002 - PostgreSQL for relational data](0002-postgresql-for-relational-data.md) +- [0003 - TypeORM for NestJS integration](0003-typeorm-for-nest-integration.md) +- [0004 - JWT with refresh tokens for authentication](0004-jwt-refresh-tokens-auth.md) +- [0005 - NestJS as the primary framework](0005-nestjs-opinionated-framework.md) +- [0006 - Winston for structured logging](0006-winston-structured-logging.md) +- [0007 - Security and validation defaults](0007-security-validation-defaults.md) + +## Process + +For information on how to contribute and document new architectural decisions, see [CONTRIBUTING.md](../../CONTRIBUTING.md).