How speakstack/speak-stack-api works
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: app.module.ts App Module · database.config.ts DB Config · common Common Core · post.module.ts Posts
Components 28
Application Shell
Entrypoint, module composition, and cross-cutting request handling.
- Bootstrap · Starts the HTTP application and wires global middleware/filters.
src/main.ts - App Module · Assembles the feature modules into the running application.
src/app.module.ts - Common Core · Global exception handling, response transformation, decorators, and shared error model.
src/common
Core Content
Question, answer, comment, voting, and tagging flows.
- Posts · Post lifecycle and post-facing API endpoints.
src/post/post.module.ts - Post API · Handles post requests and routes them into application logic.
src/post/post.controller.ts - Post Service · Implements post use cases and persistence coordination.
src/post/post.service.ts - Answers · Answer API and answer persistence boundary.
src/answer/answer.module.ts - Answer API · Handles answer requests and post-answer subroutes.
src/answer/answer.controller.ts - Answer Service · Implements answer use cases and persistence coordination.
src/answer/answer.service.ts - Comments · Commenting boundary for content discussions.
src/comment/comment.module.ts - Comment API · Handles comment requests.
src/comment/comment.controller.ts - Votes · Separate vote handling for posts and answers.
src/vote/vote.module.ts - Vote Service · Coordinates vote actions and downstream effects.
src/vote/vote.service.ts - Tags · Tag taxonomy and tag API.
src/tag/tag.module.ts
Identity
Authentication, user profiles, and reputation.
- Auth · Token-based authentication and email verification.
src/auth/auth.module.ts - Auth API · Authentication and verification endpoints.
src/auth/auth.controller.ts - Auth Service · Login, token issuance, and verification workflows.
src/auth/auth.service.ts - Users · Profile management and current-user flows.
src/user/user.module.ts - User API · User profile endpoints.
src/user/user.controller.ts - Reputation · Tracks reputation changes as a history of events.
src/reputation/reputation.module.ts
Language Features
Language metadata, user-language mapping, and grammar checks.
- Languages · Language catalog and lookup API.
src/language/language.module.ts - User Languages · Many-to-many mapping between users and languages.
src/user-language/user-language.module.ts - Grammar · Dedicated grammar-check API surface.
src/grammar/grammar.module.ts
Platform Services
Shared supporting services and operational endpoints.
Data Layer
ORM configuration, entities, and seed/bootstrap data.
Connections 48
- 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.