# mwanago/nestjs-typescript architecture

> Architecture diagram of the GitHub repository mwanago/nestjs-typescript, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mwanago/nestjs-typescript
- Repository: https://github.com/mwanago/nestjs-typescript

## Overview

#### Purpose and Runtime
This is a TypeScript/NestJS backend starter expanded into a multi-domain API platform: users/authentication, content, catalog, payments, messaging, files, and operations. It runs on Node.js; bootstrap and application composition are in `src/main.ts` and `src/app.module.ts`. `src/repl.ts` provides a separate interactive Nest application entry point.

#### Application Composition and Transport Boundaries
`src/app.module.ts` is the dependency-composition root, wiring feature modules around shared database, logging, search, PubSub, and health capabilities. Most domain APIs use REST controllers, while posts also expose GraphQL through `src/posts/posts.resolver.ts` and the generated schema `src/schema.gql`. Real-time chat is a gateway boundary in `src/chat/chat.gateway.ts`; subscribers define a protobuf contract at `src/subscribers/subscribers.proto`, indicating a service/RPC integration boundary.

#### Persistence and Operational Cross-Cutting Layer
Database-backed entities are distributed by domain, with infrastructure rooted in `src/database/database.module.ts` and database logging in `src/database/databaseLogger.ts`. Core persisted aggregates include users (`src/users/user.entity.ts`), posts (`src/posts/post.entity.ts`), and Stripe webhook events (`src/stripeWebhook/StripeEvent.entity.ts`). Cross-cutting request processing includes logging middleware (`src/utils/logs.middleware.ts`), raw-body handling for signed webhook verification (`src/utils/rawBody.middleware.ts`), and null-value response normalization (`src/utils/excludeNull.interceptor.ts`).

#### Identity, Authorization, and Account Verification
Authentication is centered on `src/authentication/authentication.service.ts` and exposed through `src/authentication/authentication.controller.ts`. It supports local credentials plus JWT access, refresh, and two-factor strategies/guards, with authorization boundaries implemented in `src/authentication/jwt-authentication.guard.ts` and `src/authentication/jwt-refresh.guard.ts`. Account lifecycle extends to email verification (`src/emailConfirmation/emailConfirmation.service.ts`), Google authentication (`src/googleAuthentication/googleAuthentication.service.ts`), and SMS/two-factor verification (`src/sms/sms.service.ts`).

#### Content, Query, and Caching Flow
Posts are the richest content domain: REST and GraphQL requests enter `src/posts/posts.controller.ts` or `src/posts/posts.resolver.ts`, then flow through `src/posts/posts.service.ts` to persistence. Search is separated into `src/posts/postsSearch.service.ts`, with Elasticsearch explicitly represented by `src/health/elasticsearchHealthIndicator.ts`. HTTP cache behavior is scoped to posts in `src/posts/httpCache.interceptor.ts`. Comments use CQRS-style command/query dispatch, with write and read handlers at `src/comments/commands/handlers/create-comment.handler.ts` and `src/comments/queries/handlers/getComments.handler.ts`.

#### Commerce and External Payment Processing
Product catalog management is divided between product categories and products: `src/productCategories/productCategories.service.ts` and `src/products/products.service.ts`. Payment operations are mediated by `src/stripe/stripe.service.ts`; charge and saved-card HTTP endpoints are in `src/charge/charge.controller.ts` and `src/credit-cards/creditCards.controller.ts`. Stripe callbacks enter the dedicated webhook controller/service boundary (`src/stripeWebhook/stripeWebhook.controller.ts`, `src/stripeWebhook/stripeWebhook.service.ts`), which requires raw request bodies and records webhook events.

#### Communications, Files, and Background-Facing Services
Email delivery and scheduling are distinct capabilities in `src/email/email.service.ts` and `src/emailScheduling/emailScheduling.service.ts`; SMS is handled separately. File metadata/storage is modeled through `src/files/files.service.ts`, while local upload handling is isolated in `src/localFiles/localFiles.service.ts`. Image optimization is exposed as a dedicated processing boundary in `src/optimize/image.processor.ts`. `docker-compose.yml` is the repository’s infrastructure orchestration entry point; Elasticsearch is materially implied by the search and health components.

Main entry points: [`src/app.module.ts`](https://github.com/mwanago/nestjs-typescript/blob/master/src/app.module.ts) (Application composition), [`src/stripeWebhook/stripeWebhook.controller.ts`](https://github.com/mwanago/nestjs-typescript/blob/master/src/stripeWebhook/stripeWebhook.controller.ts) (Stripe webhooks), [`src/database/database.module.ts`](https://github.com/mwanago/nestjs-typescript/blob/master/src/database/database.module.ts) (Database layer), [`src/authentication/authentication.service.ts`](https://github.com/mwanago/nestjs-typescript/blob/master/src/authentication/authentication.service.ts) (Authentication API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_bootstrap{{"Nest bootstrap<br/>Node entry<br/>[main.ts]"}}
  node_app["Application composition<br/>Nest module root<br/>[app.module.ts]"]
  node_repl{{"Interactive REPL<br/>Nest entry<br/>[repl.ts]"}}
  node_database[("Database layer<br/>Persistence module<br/>[database.module.ts]")]
  node_request_processing["Request processing<br/>Middleware &amp; interceptor"]
end

subgraph group_identity["Identity"]
  node_auth["Authentication API<br/>Controller &amp; service"]
  node_auth_guards["JWT guards<br/>Authorization boundary"]
  node_account_verification["Account verification<br/>Identity integrations"]
  node_users[("Users<br/>Persisted aggregate<br/>[user.entity.ts]")]
end

subgraph group_content["Content"]
  node_posts_api["Posts REST &amp; GraphQL<br/>Transport boundary"]
  node_posts["Posts service<br/>Content domain service<br/>[posts.service.ts]"]
  node_post_entity[("Posts<br/>Persisted aggregate<br/>[post.entity.ts]")]
  node_post_search["Post search<br/>Search service"]
  node_elasticsearch[("Elasticsearch<br/>Search &amp; health dependency")]
  node_comments_cqrs["Comments CQRS<br/>Command/query handlers"]
end

subgraph group_commerce["Commerce"]
  node_catalog["Catalog services<br/>Products &amp; categories"]
  node_payments["Stripe payments<br/>Payment service<br/>[stripe.service.ts]"]
  node_stripe_webhooks["Stripe webhooks<br/>Webhook boundary"]
  node_stripe_events[("Webhook events<br/>Persisted aggregate")]
end

subgraph group_communications["Communications &amp; Files"]
  node_messaging["Email &amp; scheduling<br/>Delivery services<br/>[email.service.ts]"]
  node_files["Files &amp; image processing<br/>Storage pipeline<br/>[files.service.ts]"]
  node_chat_rpc["Chat &amp; subscriber RPC<br/>Realtime integration boundary<br/>[chat.gateway.ts]"]
end

node_bootstrap -->|"boots"| node_app
node_repl -->|"creates app"| node_app
node_app -->|"configures"| node_database
node_app -->|"applies"| node_request_processing
node_app -->|"mounts"| node_auth
node_app -->|"mounts"| node_posts_api
node_app -->|"mounts"| node_catalog
node_app -->|"mounts"| node_payments
node_app -->|"mounts"| node_chat_rpc
node_request_processing -->|"raw body for"| node_stripe_webhooks
node_auth -->|"issues tokens for"| node_auth_guards
node_auth -->|"authenticates"| node_users
node_account_verification -->|"verifies accounts"| node_users
node_posts_api -->|"invokes"| node_posts
node_posts -->|"persists"| node_post_entity
node_posts -->|"indexes/searches"| node_post_search
node_post_search -->|"queries"| node_elasticsearch
node_comments_cqrs -->|"reads and writes"| node_database
node_catalog -->|"persists"| node_database
node_payments -.->|"receives callbacks"| node_stripe_webhooks
node_stripe_webhooks -->|"records"| node_stripe_events
node_stripe_webhooks -->|"processes events"| node_payments
node_messaging -->|"delivers verification"| node_account_verification
node_files -->|"stores metadata"| node_database

click node_bootstrap "https://github.com/mwanago/nestjs-typescript/blob/master/src/main.ts"
click node_app "https://github.com/mwanago/nestjs-typescript/blob/master/src/app.module.ts"
click node_repl "https://github.com/mwanago/nestjs-typescript/blob/master/src/repl.ts"
click node_database "https://github.com/mwanago/nestjs-typescript/blob/master/src/database/database.module.ts"
click node_request_processing "https://github.com/mwanago/nestjs-typescript/blob/master/src/utils/rawBody.middleware.ts"
click node_auth "https://github.com/mwanago/nestjs-typescript/blob/master/src/authentication/authentication.service.ts"
click node_auth_guards "https://github.com/mwanago/nestjs-typescript/blob/master/src/authentication/jwt-authentication.guard.ts"
click node_account_verification "https://github.com/mwanago/nestjs-typescript/blob/master/src/emailConfirmation/emailConfirmation.service.ts"
click node_users "https://github.com/mwanago/nestjs-typescript/blob/master/src/users/user.entity.ts"
click node_posts_api "https://github.com/mwanago/nestjs-typescript/blob/master/src/posts/posts.controller.ts"
click node_posts "https://github.com/mwanago/nestjs-typescript/blob/master/src/posts/posts.service.ts"
click node_post_entity "https://github.com/mwanago/nestjs-typescript/blob/master/src/posts/post.entity.ts"
click node_post_search "https://github.com/mwanago/nestjs-typescript/blob/master/src/posts/postsSearch.service.ts"
click node_elasticsearch "https://github.com/mwanago/nestjs-typescript/blob/master/src/health/elasticsearchHealthIndicator.ts"
click node_comments_cqrs "https://github.com/mwanago/nestjs-typescript/blob/master/src/comments/commands/handlers/create-comment.handler.ts"
click node_catalog "https://github.com/mwanago/nestjs-typescript/blob/master/src/products/products.service.ts"
click node_payments "https://github.com/mwanago/nestjs-typescript/blob/master/src/stripe/stripe.service.ts"
click node_stripe_webhooks "https://github.com/mwanago/nestjs-typescript/blob/master/src/stripeWebhook/stripeWebhook.controller.ts"
click node_stripe_events "https://github.com/mwanago/nestjs-typescript/blob/master/src/stripeWebhook/StripeEvent.entity.ts"
click node_messaging "https://github.com/mwanago/nestjs-typescript/blob/master/src/email/email.service.ts"
click node_files "https://github.com/mwanago/nestjs-typescript/blob/master/src/files/files.service.ts"
click node_chat_rpc "https://github.com/mwanago/nestjs-typescript/blob/master/src/chat/chat.gateway.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_bootstrap,node_app,node_repl,node_database,node_request_processing toneBlue
class node_auth,node_auth_guards,node_account_verification,node_users toneAmber
class node_posts_api,node_posts,node_post_entity,node_post_search,node_elasticsearch,node_comments_cqrs toneMint
class node_catalog,node_payments,node_stripe_webhooks,node_stripe_events toneRose
class node_messaging,node_files,node_chat_rpc toneIndigo
```

## Components

### Runtime

- [Nest bootstrap](https://github.com/mwanago/nestjs-typescript/blob/master/src/main.ts): Node entry · `src/main.ts`
- [Application composition](https://github.com/mwanago/nestjs-typescript/blob/master/src/app.module.ts): Nest module root · Wires domain modules and shared capabilities. · `src/app.module.ts`
- [Interactive REPL](https://github.com/mwanago/nestjs-typescript/blob/master/src/repl.ts): Nest entry · `src/repl.ts`
- [Database layer](https://github.com/mwanago/nestjs-typescript/blob/master/src/database/database.module.ts): Persistence module · Provides database-backed domain persistence. · `src/database/database.module.ts`
- [Request processing](https://github.com/mwanago/nestjs-typescript/blob/master/src/utils/rawBody.middleware.ts): Middleware & interceptor · Logging, raw-body handling, and null normalization. · `src/utils/rawBody.middleware.ts`

### Identity

- [Authentication API](https://github.com/mwanago/nestjs-typescript/blob/master/src/authentication/authentication.service.ts): Controller & service · Local, JWT, refresh, and two-factor authentication. · `src/authentication/authentication.service.ts`
- [JWT guards](https://github.com/mwanago/nestjs-typescript/blob/master/src/authentication/jwt-authentication.guard.ts): Authorization boundary · `src/authentication/jwt-authentication.guard.ts`
- [Account verification](https://github.com/mwanago/nestjs-typescript/blob/master/src/emailConfirmation/emailConfirmation.service.ts): Identity integrations · Email, Google, and SMS/two-factor verification. · `src/emailConfirmation/emailConfirmation.service.ts`
- [Users](https://github.com/mwanago/nestjs-typescript/blob/master/src/users/user.entity.ts): Persisted aggregate · `src/users/user.entity.ts`

### Content

- [Posts REST & GraphQL](https://github.com/mwanago/nestjs-typescript/blob/master/src/posts/posts.controller.ts): Transport boundary · Exposes REST and GraphQL post operations. · `src/posts/posts.controller.ts`
- [Posts service](https://github.com/mwanago/nestjs-typescript/blob/master/src/posts/posts.service.ts): Content domain service · `src/posts/posts.service.ts`
- [Posts](https://github.com/mwanago/nestjs-typescript/blob/master/src/posts/post.entity.ts): Persisted aggregate · `src/posts/post.entity.ts`
- [Post search](https://github.com/mwanago/nestjs-typescript/blob/master/src/posts/postsSearch.service.ts): Search service · `src/posts/postsSearch.service.ts`
- [Elasticsearch](https://github.com/mwanago/nestjs-typescript/blob/master/src/health/elasticsearchHealthIndicator.ts): Search & health dependency · Used by post search and health checks. · `src/health/elasticsearchHealthIndicator.ts`
- [Comments CQRS](https://github.com/mwanago/nestjs-typescript/blob/master/src/comments/commands/handlers/create-comment.handler.ts): Command/query handlers · Separates comment writes from reads. · `src/comments/commands/handlers/create-comment.handler.ts`

### Commerce

- [Catalog services](https://github.com/mwanago/nestjs-typescript/blob/master/src/products/products.service.ts): Products & categories · `src/products/products.service.ts`
- [Stripe payments](https://github.com/mwanago/nestjs-typescript/blob/master/src/stripe/stripe.service.ts): Payment service · Mediates charges and saved-card operations. · `src/stripe/stripe.service.ts`
- [Stripe webhooks](https://github.com/mwanago/nestjs-typescript/blob/master/src/stripeWebhook/stripeWebhook.controller.ts): Webhook boundary · Verifies signed callbacks and records events. · `src/stripeWebhook/stripeWebhook.controller.ts`
- [Webhook events](https://github.com/mwanago/nestjs-typescript/blob/master/src/stripeWebhook/StripeEvent.entity.ts): Persisted aggregate · `src/stripeWebhook/StripeEvent.entity.ts`

### Communications & Files

- [Email & scheduling](https://github.com/mwanago/nestjs-typescript/blob/master/src/email/email.service.ts): Delivery services · `src/email/email.service.ts`
- [Files & image processing](https://github.com/mwanago/nestjs-typescript/blob/master/src/files/files.service.ts): Storage pipeline · File metadata, local uploads, and image optimization. · `src/files/files.service.ts`
- [Chat & subscriber RPC](https://github.com/mwanago/nestjs-typescript/blob/master/src/chat/chat.gateway.ts): Realtime integration boundary · Chat gateway and protobuf subscriber contract. · `src/chat/chat.gateway.ts`

## Connections

- Nest bootstrap → Application composition: boots
- Interactive REPL → Application composition: creates app
- Application composition → Database layer: configures
- Application composition → Request processing: applies
- Application composition → Authentication API: mounts
- Application composition → Posts REST & GraphQL: mounts
- Application composition → Catalog services: mounts
- Application composition → Stripe payments: mounts
- Application composition → Chat & subscriber RPC: mounts
- Request processing → Stripe webhooks: raw body for
- Authentication API → JWT guards: issues tokens for
- Authentication API → Users: authenticates
- Account verification → Users: verifies accounts
- Posts REST & GraphQL → Posts service: invokes
- Posts service → Posts: persists
- Posts service → Post search: indexes/searches
- Post search → Elasticsearch: queries
- Comments CQRS → Database layer: reads and writes
- Catalog services → Database layer: persists
- Stripe payments → Stripe webhooks: receives callbacks
- Stripe webhooks → Webhook events: records
- Stripe webhooks → Stripe payments: processes events
- Email & scheduling → Account verification: delivers verification
- Files & image processing → Database layer: stores metadata