# speakstack/speak-stack-api architecture

> Architecture diagram of the GitHub repository speakstack/speak-stack-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/speakstack/speak-stack-api
- Repository: https://github.com/speakstack/speak-stack-api

## Overview

1. This is a NestJS backend in TypeScript running on Node.js. The repository is organized as a modular HTTP API: each feature area has its own module, controller(s), service, DTOs, and persistence entities, which makes the module graph the main architectural boundary.

2. The entrypoint is `src/main.ts`, with the application root assembled in `src/app.module.ts`. Cross-cutting behavior is centralized in `src/common`: a global exception filter, a response-transform interceptor, custom decorators, and a shared `AppException`/error-code model. That means request handling is not just controller-to-service; it also passes through consistent error and response shaping.

3. Persistence is entity-driven and likely relational. The presence of many `entities/*.entity.ts` files, `database.config.ts`, and a `snake-naming.strategy.ts` indicates a database ORM layer that maps Nest modules to tables with snake_case naming. `seed.ts` suggests bootstrapping reference data into the database.

4. The domain is a community/Q&A-style platform. Core content modules are `post`, `answer`, `comment`, `vote`, and `tag`. Posts and answers have dedicated DTOs and entities, comments are a separate module, and votes are split into `post-vote` and `answer-vote` controllers/entities, which suggests voting is handled per content type rather than by a single generic endpoint.

5. User identity and access are handled by `auth` and `user`. `auth` includes an access-token strategy/guard (`at.strategy.ts`, `at.guard.ts`), email verification entity, and token types, which points to token-based authentication plus account verification. `user` owns profile data and update flows, while `public` and `get-current-user` decorators indicate endpoints can be selectively anonymous or tied to the authenticated principal.

6. Reputation is modeled as its own subsystem. `reputation-history.entity.ts` shows the system tracks reputation changes as events/history rather than only storing a single counter, which is important for diagramming because vote actions likely fan out into reputation updates.

7. Language support is a first-class domain boundary. There are separate `language` and `user-language` modules, with `user-languages.controller.ts` alongside the standard controller/service pair. That suggests a many-to-many relationship between users and languages, probably used for matching content, profiles, or grammar-related features.

8. Grammar checking is isolated in its own module (`grammar`). The controller/service/DTOs imply a dedicated API surface for submitting text and receiving check results. It is architecturally separate from posts/comments, so it likely consumes content from the application rather than being embedded inside post creation.

9. Mail delivery is abstracted behind `mail.module.ts` and `mail.service.ts`. Combined with the email verification entity in auth, this indicates outbound email is a supporting service used by auth flows rather than a core business domain.

10. Operational endpoints are explicit: `health` is separated into its own module/controller for liveness/readiness checks. This is useful for deployment and container orchestration, and it keeps infrastructure monitoring out of the business modules.

11. The API surface is controller-heavy and REST-like, with feature-specific routes split by concern rather than a single monolith controller. DTOs sit between controllers and services for input/output shaping, while entities define persistence. The architecture diagram should show: client requests -> controllers -> services -> entities/DB, with auth/guards, global exception handling, response transformation, and supporting services like mail and grammar as shared platform concerns around the core content modules.

Main entry points: [`src/app.module.ts`](https://github.com/speakstack/speak-stack-api/blob/main/src/app.module.ts) (App Module), [`src/config/database.config.ts`](https://github.com/speakstack/speak-stack-api/blob/main/src/config/database.config.ts) (DB Config), [`src/common`](https://github.com/speakstack/speak-stack-api/tree/main/src/common) (Common Core), [`src/post/post.module.ts`](https://github.com/speakstack/speak-stack-api/blob/main/src/post/post.module.ts) (Posts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_app["Application Shell"]
  node_main["Bootstrap<br/>Nest entrypoint<br/>[main.ts]"]
  node_app_module["App Module<br/>Composition root<br/>[app.module.ts]"]
  node_common{{"Common Core<br/>Cross-cutting"}}
end

subgraph group_grp_content["Core Content"]
  node_post_module["Posts<br/>Feature module<br/>[post.module.ts]"]
  node_post_controller["Post API<br/>Controller<br/>[post.controller.ts]"]
  node_post_service["Post Service<br/>[post.service.ts]"]
  node_answer_module["Answers<br/>Feature module<br/>[answer.module.ts]"]
  node_answer_controller["Answer API<br/>Controller"]
  node_answer_service["Answer Service<br/>[answer.service.ts]"]
  node_comment_module["Comments<br/>Feature module<br/>[comment.module.ts]"]
  node_comment_controller["Comment API<br/>Controller"]
  node_vote_module["Votes<br/>Feature module<br/>[vote.module.ts]"]
  node_vote_service["Vote Service<br/>[vote.service.ts]"]
  node_tag_module["Tags<br/>Feature module<br/>[tag.module.ts]"]
end

subgraph group_grp_identity["Identity"]
  node_auth_module["Auth<br/>Feature module<br/>[auth.module.ts]"]
  node_auth_controller["Auth API<br/>Controller<br/>[auth.controller.ts]"]
  node_auth_service["Auth Service<br/>[auth.service.ts]"]
  node_user_module["Users<br/>Feature module<br/>[user.module.ts]"]
  node_user_controller["User API<br/>Controller<br/>[user.controller.ts]"]
  node_reputation_module["Reputation<br/>Subsystem"]
end

subgraph group_grp_language["Language Features"]
  node_language_module["Languages<br/>Feature module<br/>[language.module.ts]"]
  node_user_language_module["User Languages<br/>Feature module"]
  node_grammar_module["Grammar<br/>Feature module<br/>[grammar.module.ts]"]
end

subgraph group_grp_platform["Platform Services"]
  node_health_module["Health<br/>Operational module<br/>[health.module.ts]"]
  node_mail_module["Mail<br/>Support service<br/>[mail.module.ts]"]
end

subgraph group_grp_data["Data Layer"]
  node_db_config[("DB Config<br/>ORM config<br/>[database.config.ts]")]
  node_entities[("Entities<br/>Persistence model")]
  node_seed["Seed<br/>Bootstrap script<br/>[seed.ts]"]
end

node_main -->|"starts"| node_app_module
node_app_module -->|"applies"| node_common
node_app_module -->|"loads"| node_post_module
node_app_module -->|"loads"| node_answer_module
node_app_module -->|"loads"| node_comment_module
node_app_module -->|"loads"| node_vote_module
node_app_module -->|"loads"| node_tag_module
node_app_module -->|"loads"| node_auth_module
node_app_module -->|"loads"| node_user_module
node_app_module -->|"loads"| node_reputation_module
node_app_module -->|"loads"| node_language_module
node_app_module -->|"loads"| node_user_language_module
node_app_module -->|"loads"| node_grammar_module
node_app_module -->|"loads"| node_health_module
node_app_module -->|"loads"| node_mail_module
node_post_module -->|"exports"| node_post_controller
node_post_module -->|"provides"| node_post_service
node_answer_module -->|"exports"| node_answer_controller
node_answer_module -->|"provides"| node_answer_service
node_comment_module -->|"exports"| node_comment_controller
node_vote_module -->|"provides"| node_vote_service
node_auth_module -->|"exports"| node_auth_controller
node_auth_module -->|"provides"| node_auth_service
node_user_module -->|"exports"| node_user_controller
node_post_controller -->|"uses"| node_post_service
node_answer_controller -->|"uses"| node_answer_service
node_comment_controller -.->|"reads"| node_post_service
node_vote_service -.->|"updates"| node_reputation_module
node_auth_service -.->|"sends"| node_mail_module
node_auth_service -.->|"affects"| node_user_module
node_user_module -.->|"links"| node_user_language_module
node_user_language_module -.->|"references"| node_language_module
node_grammar_module -.->|"uses"| node_language_module
node_post_module -->|"persists via"| node_db_config
node_answer_module -->|"persists via"| node_db_config
node_comment_module -->|"persists via"| node_db_config
node_vote_module -->|"persists via"| node_db_config
node_auth_module -->|"persists via"| node_db_config
node_user_module -->|"persists via"| node_db_config
node_language_module -->|"persists via"| node_db_config
node_user_language_module -->|"persists via"| node_db_config
node_reputation_module -->|"persists via"| node_db_config
node_db_config -->|"maps"| node_entities
node_seed -.->|"bootstraps"| node_db_config
node_common -.->|"protects"| node_auth_module
node_common -.->|"shapes"| node_post_module
node_common -.->|"shapes"| node_answer_module
node_common -.->|"shapes"| node_comment_module

click node_main "https://github.com/speakstack/speak-stack-api/blob/main/src/main.ts"
click node_app_module "https://github.com/speakstack/speak-stack-api/blob/main/src/app.module.ts"
click node_common "https://github.com/speakstack/speak-stack-api/tree/main/src/common"
click node_post_module "https://github.com/speakstack/speak-stack-api/blob/main/src/post/post.module.ts"
click node_post_controller "https://github.com/speakstack/speak-stack-api/blob/main/src/post/post.controller.ts"
click node_post_service "https://github.com/speakstack/speak-stack-api/blob/main/src/post/post.service.ts"
click node_answer_module "https://github.com/speakstack/speak-stack-api/blob/main/src/answer/answer.module.ts"
click node_answer_controller "https://github.com/speakstack/speak-stack-api/blob/main/src/answer/answer.controller.ts"
click node_answer_service "https://github.com/speakstack/speak-stack-api/blob/main/src/answer/answer.service.ts"
click node_comment_module "https://github.com/speakstack/speak-stack-api/blob/main/src/comment/comment.module.ts"
click node_comment_controller "https://github.com/speakstack/speak-stack-api/blob/main/src/comment/comment.controller.ts"
click node_vote_module "https://github.com/speakstack/speak-stack-api/blob/main/src/vote/vote.module.ts"
click node_vote_service "https://github.com/speakstack/speak-stack-api/blob/main/src/vote/vote.service.ts"
click node_tag_module "https://github.com/speakstack/speak-stack-api/blob/main/src/tag/tag.module.ts"
click node_auth_module "https://github.com/speakstack/speak-stack-api/blob/main/src/auth/auth.module.ts"
click node_auth_controller "https://github.com/speakstack/speak-stack-api/blob/main/src/auth/auth.controller.ts"
click node_auth_service "https://github.com/speakstack/speak-stack-api/blob/main/src/auth/auth.service.ts"
click node_user_module "https://github.com/speakstack/speak-stack-api/blob/main/src/user/user.module.ts"
click node_user_controller "https://github.com/speakstack/speak-stack-api/blob/main/src/user/user.controller.ts"
click node_reputation_module "https://github.com/speakstack/speak-stack-api/blob/main/src/reputation/reputation.module.ts"
click node_language_module "https://github.com/speakstack/speak-stack-api/blob/main/src/language/language.module.ts"
click node_user_language_module "https://github.com/speakstack/speak-stack-api/blob/main/src/user-language/user-language.module.ts"
click node_grammar_module "https://github.com/speakstack/speak-stack-api/blob/main/src/grammar/grammar.module.ts"
click node_health_module "https://github.com/speakstack/speak-stack-api/blob/main/src/health/health.module.ts"
click node_mail_module "https://github.com/speakstack/speak-stack-api/blob/main/src/mail/mail.module.ts"
click node_db_config "https://github.com/speakstack/speak-stack-api/blob/main/src/config/database.config.ts"
click node_entities "https://github.com/speakstack/speak-stack-api/tree/main/src"
click node_seed "https://github.com/speakstack/speak-stack-api/blob/main/src/seed.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_main,node_app_module,node_common toneBlue
class node_post_module,node_post_controller,node_post_service,node_answer_module,node_answer_controller,node_answer_service,node_comment_module,node_comment_controller,node_vote_module,node_vote_service,node_tag_module toneAmber
class node_auth_module,node_auth_controller,node_auth_service,node_user_module,node_user_controller,node_reputation_module toneMint
class node_language_module,node_user_language_module,node_grammar_module toneRose
class node_health_module,node_mail_module toneIndigo
class node_db_config,node_entities,node_seed toneTeal
```

## Components

### Application Shell

Entrypoint, module composition, and cross-cutting request handling.

- [Bootstrap](https://github.com/speakstack/speak-stack-api/blob/main/src/main.ts): Nest entrypoint · Starts the HTTP application and wires global middleware/filters. · `src/main.ts`
- [App Module](https://github.com/speakstack/speak-stack-api/blob/main/src/app.module.ts): Composition root · Assembles the feature modules into the running application. · `src/app.module.ts`
- [Common Core](https://github.com/speakstack/speak-stack-api/tree/main/src/common): Cross-cutting · Global exception handling, response transformation, decorators, and shared error model. · `src/common`

### Core Content

Question, answer, comment, voting, and tagging flows.

- [Posts](https://github.com/speakstack/speak-stack-api/blob/main/src/post/post.module.ts): Feature module · Post lifecycle and post-facing API endpoints. · `src/post/post.module.ts`
- [Post API](https://github.com/speakstack/speak-stack-api/blob/main/src/post/post.controller.ts): Controller · Handles post requests and routes them into application logic. · `src/post/post.controller.ts`
- [Post Service](https://github.com/speakstack/speak-stack-api/blob/main/src/post/post.service.ts): Service · Implements post use cases and persistence coordination. · `src/post/post.service.ts`
- [Answers](https://github.com/speakstack/speak-stack-api/blob/main/src/answer/answer.module.ts): Feature module · Answer API and answer persistence boundary. · `src/answer/answer.module.ts`
- [Answer API](https://github.com/speakstack/speak-stack-api/blob/main/src/answer/answer.controller.ts): Controller · Handles answer requests and post-answer subroutes. · `src/answer/answer.controller.ts`
- [Answer Service](https://github.com/speakstack/speak-stack-api/blob/main/src/answer/answer.service.ts): Service · Implements answer use cases and persistence coordination. · `src/answer/answer.service.ts`
- [Comments](https://github.com/speakstack/speak-stack-api/blob/main/src/comment/comment.module.ts): Feature module · Commenting boundary for content discussions. · `src/comment/comment.module.ts`
- [Comment API](https://github.com/speakstack/speak-stack-api/blob/main/src/comment/comment.controller.ts): Controller · Handles comment requests. · `src/comment/comment.controller.ts`
- [Votes](https://github.com/speakstack/speak-stack-api/blob/main/src/vote/vote.module.ts): Feature module · Separate vote handling for posts and answers. · `src/vote/vote.module.ts`
- [Vote Service](https://github.com/speakstack/speak-stack-api/blob/main/src/vote/vote.service.ts): Service · Coordinates vote actions and downstream effects. · `src/vote/vote.service.ts`
- [Tags](https://github.com/speakstack/speak-stack-api/blob/main/src/tag/tag.module.ts): Feature module · Tag taxonomy and tag API. · `src/tag/tag.module.ts`

### Identity

Authentication, user profiles, and reputation.

- [Auth](https://github.com/speakstack/speak-stack-api/blob/main/src/auth/auth.module.ts): Feature module · Token-based authentication and email verification. · `src/auth/auth.module.ts`
- [Auth API](https://github.com/speakstack/speak-stack-api/blob/main/src/auth/auth.controller.ts): Controller · Authentication and verification endpoints. · `src/auth/auth.controller.ts`
- [Auth Service](https://github.com/speakstack/speak-stack-api/blob/main/src/auth/auth.service.ts): Service · Login, token issuance, and verification workflows. · `src/auth/auth.service.ts`
- [Users](https://github.com/speakstack/speak-stack-api/blob/main/src/user/user.module.ts): Feature module · Profile management and current-user flows. · `src/user/user.module.ts`
- [User API](https://github.com/speakstack/speak-stack-api/blob/main/src/user/user.controller.ts): Controller · User profile endpoints. · `src/user/user.controller.ts`
- [Reputation](https://github.com/speakstack/speak-stack-api/blob/main/src/reputation/reputation.module.ts): Subsystem · Tracks reputation changes as a history of events. · `src/reputation/reputation.module.ts`

### Language Features

Language metadata, user-language mapping, and grammar checks.

- [Languages](https://github.com/speakstack/speak-stack-api/blob/main/src/language/language.module.ts): Feature module · Language catalog and lookup API. · `src/language/language.module.ts`
- [User Languages](https://github.com/speakstack/speak-stack-api/blob/main/src/user-language/user-language.module.ts): Feature module · Many-to-many mapping between users and languages. · `src/user-language/user-language.module.ts`
- [Grammar](https://github.com/speakstack/speak-stack-api/blob/main/src/grammar/grammar.module.ts): Feature module · Dedicated grammar-check API surface. · `src/grammar/grammar.module.ts`

### Platform Services

Shared supporting services and operational endpoints.

- [Health](https://github.com/speakstack/speak-stack-api/blob/main/src/health/health.module.ts): Operational module · Liveness and readiness endpoints. · `src/health/health.module.ts`
- [Mail](https://github.com/speakstack/speak-stack-api/blob/main/src/mail/mail.module.ts): Support service · Outbound email abstraction used by auth flows. · `src/mail/mail.module.ts`

### Data Layer

ORM configuration, entities, and seed/bootstrap data.

- [DB Config](https://github.com/speakstack/speak-stack-api/blob/main/src/config/database.config.ts): ORM config · Database configuration and naming strategy setup. · `src/config/database.config.ts`
- [Entities](https://github.com/speakstack/speak-stack-api/tree/main/src): Persistence model · Relational entities for users, content, votes, languages, and reputation. · `src`
- [Seed](https://github.com/speakstack/speak-stack-api/blob/main/src/seed.ts): Bootstrap script · Loads reference data into the database. · `src/seed.ts`

## Connections

- Bootstrap → App Module: starts · Bootstraps the application through the root module.
- App Module → Common Core: applies · Registers shared filters, interceptors, and decorators.
- App Module → Posts: loads · Composes the post feature into the app.
- App Module → Answers: loads · Composes the answer feature into the app.
- App Module → Comments: loads · Composes the comment feature into the app.
- App Module → Votes: loads · Composes the voting feature into the app.
- App Module → Tags: loads · Composes tagging into the app.
- App Module → Auth: loads · Composes authentication into the app.
- App Module → Users: loads · Composes user management into the app.
- App Module → Reputation: loads · Composes reputation tracking into the app.
- App Module → Languages: loads · Composes language catalog features into the app.
- App Module → User Languages: loads · Composes user-language mapping into the app.
- App Module → Grammar: loads · Composes grammar checking into the app.
- App Module → Health: loads · Adds operational health endpoints.
- App Module → Mail: loads · Adds outbound mail support.
- Posts → Post API: exports · Exposes the post HTTP surface.
- Posts → Post Service: provides · Provides post business logic.
- Answers → Answer API: exports · Exposes the answer HTTP surface.
- Answers → Answer Service: provides · Provides answer business logic.
- Comments → Comment API: exports · Exposes the comment HTTP surface.
- Votes → Vote Service: provides · Provides vote orchestration logic.
- Auth → Auth API: exports · Exposes auth endpoints.
- Auth → Auth Service: provides · Provides authentication logic.
- Users → User API: exports · Exposes user profile endpoints.
- Post API → Post Service: uses · Delegates request handling to service logic.
- Answer API → Answer Service: uses · Delegates request handling to service logic.
- Comment API → Post Service: reads · Comment flows attach to content context.
- Vote Service → Reputation: updates · Vote events can fan out into reputation history.
- Auth Service → Mail: sends · Uses mail for verification and account flows.
- Auth Service → Users: affects · Authentication is tied to user accounts and principals.
- Users → User Languages: links · User profiles relate to preferred languages.
- User Languages → Languages: references · Maps users onto cataloged languages.
- Grammar → Languages: uses · Grammar checks are language-aware.
- Posts → DB Config: persists via · Reads/writes through the ORM configuration.
- Answers → DB Config: persists via · Reads/writes through the ORM configuration.
- Comments → DB Config: persists via · Reads/writes through the ORM configuration.
- Votes → DB Config: persists via · Reads/writes through the ORM configuration.
- Auth → DB Config: persists via · Reads/writes through the ORM configuration.
- Users → DB Config: persists via · Reads/writes through the ORM configuration.
- Languages → DB Config: persists via · Reads/writes through the ORM configuration.
- User Languages → DB Config: persists via · Reads/writes through the ORM configuration.
- Reputation → DB Config: persists via · Reads/writes through the ORM configuration.
- DB Config → Entities: maps · Maps ORM configuration onto entity definitions.
- Seed → DB Config: bootstraps · Seeds data using the configured database connection.
- Common Core → Auth: protects · Public routes and current-user decorators shape access.
- Common Core → Posts: shapes · Global filters and transformers affect HTTP responses.
- Common Core → Answers: shapes · Global filters and transformers affect HTTP responses.
- Common Core → Comments: shapes · Global filters and transformers affect HTTP responses.
