# techaccecho/backend-service architecture

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

- Interactive diagram: https://gitdiagram.com/techaccecho/backend-service
- Repository: https://github.com/techaccecho/backend-service

## Overview

This monorepo provides backend APIs for BlogNET, administration, authentication/user identity, and ARG player progression; the game service is documented as reserved. Principal flows are HTTP requests through service routes and shared plugins into domain operations and Convex-backed data, or state requests through the ARG rules engine to a progression payload. The graph preserves the README’s major capabilities. Several service bootstraps and storage modules were not excerpted, so uncertain wiring is omitted or marked unverified.

Main entry points: [`apps/blog-service/src/modules/blogs/blogs.routes.ts`](https://github.com/techaccecho/backend-service/blob/main/apps/blog-service/src/modules/blogs/blogs.routes.ts) (Blog API), [`apps/state-service/src/modules/state/state.routes.ts`](https://github.com/techaccecho/backend-service/blob/main/apps/state-service/src/modules/state/state.routes.ts) (State API), [`lib/data/convex/schema.ts`](https://github.com/techaccecho/backend-service/blob/main/lib/data/convex/schema.ts) (Convex database), [`lib/starter/src/modules/auth/users.routes.ts`](https://github.com/techaccecho/backend-service/blob/main/lib/starter/src/modules/auth/users.routes.ts) (User routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_services["API services"]
  node_admin["Admin API<br/>[apis.routes.ts]"]
  node_authsvc["Auth service"]
  node_blog["Blog API<br/>[blogs.routes.ts]"]
  node_comments["Comments and replies<br/>[comments.routes.ts]"]
  node_engagement["Engagement rules"]
  node_stateapi["State API<br/>[state.routes.ts]"]
  node_game["Reserved game API"]
end

subgraph group_shared["Shared runtime"]
  node_userapi["User routes<br/>[users.routes.ts]"]
  node_authplugin["Authentication hooks<br/>[auth.hook.ts]"]
end

subgraph group_domain["Domain logic"]
  node_blogdomain["Blog domain<br/>[blog.schema.ts]"]
  node_blogcontent["Blog content<br/>[blog-content.ts]"]
  node_userdomain["User domain<br/>[user.schema.ts]"]
  node_apidomain["API definitions<br/>[api.schema.ts]"]
  node_argengine["ARG rules engine<br/>[ArgRulesEngine.ts]"]
  node_projection["Progress projection<br/>[ArgRulesEngine.ts]"]
end

subgraph group_data["Data layer"]
  node_convex[("Convex database<br/>[schema.ts]")]
  node_blogstore["Blog records<br/>[blogs.ts]"]
  node_userstore["User records<br/>[users.ts]"]
  node_stepstore["Step definitions<br/>[stepDefinitions.ts]"]
  node_playerstore["Player state<br/>[argPlayerStates.ts]"]
end

node_clients(("API clients"))

node_clients -->|"manage records"| node_admin
node_clients -->|"use blogs"| node_blog
node_clients -->|"comment and reply"| node_comments
node_clients -->|"authenticate"| node_authsvc
node_clients -->|"track progression"| node_stateapi
node_clients -.->|"future game use"| node_game
node_userapi -->|"uses hooks"| node_authplugin
node_blog -->|"uses blog schemas"| node_blogdomain
node_blog -.->|"content operations"| node_blogcontent
node_comments -->|"returns blog data"| node_blogdomain
node_admin -.->|"API management"| node_apidomain
node_userapi -->|"uses user commands"| node_userdomain
node_userdomain -->|"queries user data"| node_userstore
node_blog -.->|"reads and writes blogs"| node_blogstore
node_blogstore -.->|"persists records"| node_convex
node_userstore -.->|"persists records"| node_convex
node_stateapi -->|"evaluates progression"| node_argengine
node_stateapi -.->|"loads step definitions"| node_stepstore
node_stateapi -.->|"reads and updates state"| node_playerstore
node_argengine -->|"computes payload"| node_projection
node_stepstore -.->|"stores definitions"| node_convex
node_playerstore -.->|"stores progression"| node_convex

click node_admin "https://github.com/techaccecho/backend-service/blob/main/apps/admin-service/src/modules/apis/apis.routes.ts"
click node_authsvc "https://github.com/techaccecho/backend-service/tree/main/apps/auth-service/src"
click node_blog "https://github.com/techaccecho/backend-service/blob/main/apps/blog-service/src/modules/blogs/blogs.routes.ts"
click node_comments "https://github.com/techaccecho/backend-service/blob/main/apps/blog-service/src/modules/comments/comments.routes.ts"
click node_engagement "https://github.com/techaccecho/backend-service/blob/main/apps/blog-service/src/modules/rules-of-engagement/rules-of-engagement.routes.ts"
click node_stateapi "https://github.com/techaccecho/backend-service/blob/main/apps/state-service/src/modules/state/state.routes.ts"
click node_game "https://github.com/techaccecho/backend-service/tree/main/apps/game-service/src"
click node_userapi "https://github.com/techaccecho/backend-service/blob/main/lib/starter/src/modules/auth/users.routes.ts"
click node_authplugin "https://github.com/techaccecho/backend-service/blob/main/lib/starter/src/modules/auth/hooks/auth.hook.ts"
click node_blogdomain "https://github.com/techaccecho/backend-service/blob/main/lib/domain/src/blog/blog.schema.ts"
click node_blogcontent "https://github.com/techaccecho/backend-service/blob/main/lib/domain/src/blog/blog-content.ts"
click node_userdomain "https://github.com/techaccecho/backend-service/blob/main/lib/domain/src/user/user.schema.ts"
click node_apidomain "https://github.com/techaccecho/backend-service/blob/main/lib/domain/src/api/api.schema.ts"
click node_argengine "https://github.com/techaccecho/backend-service/blob/main/apps/state-service/src/modules/state/ArgRulesEngine.ts"
click node_convex "https://github.com/techaccecho/backend-service/blob/main/lib/data/convex/schema.ts"
click node_blogstore "https://github.com/techaccecho/backend-service/blob/main/lib/data/convex/blogs.ts"
click node_userstore "https://github.com/techaccecho/backend-service/blob/main/lib/data/convex/users.ts"
click node_stepstore "https://github.com/techaccecho/backend-service/blob/main/lib/data/convex/stepDefinitions.ts"
click node_playerstore "https://github.com/techaccecho/backend-service/blob/main/lib/data/convex/argPlayerStates.ts"
click node_projection "https://github.com/techaccecho/backend-service/blob/main/apps/state-service/src/modules/state/ArgRulesEngine.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_admin,node_authsvc,node_blog,node_comments,node_engagement,node_stateapi,node_game,node_clients toneBlue
class node_userapi,node_authplugin toneAmber
class node_blogdomain,node_blogcontent,node_userdomain,node_apidomain,node_argengine,node_projection toneMint
class node_convex,node_blogstore,node_userstore,node_stepstore,node_playerstore toneRose
```

## Components

### API services

- [Admin API](https://github.com/techaccecho/backend-service/blob/main/apps/admin-service/src/modules/apis/apis.routes.ts): `apps/admin-service/src/modules/apis/apis.routes.ts`
- [Auth service](https://github.com/techaccecho/backend-service/tree/main/apps/auth-service/src): `apps/auth-service/src`
- [Blog API](https://github.com/techaccecho/backend-service/blob/main/apps/blog-service/src/modules/blogs/blogs.routes.ts): `apps/blog-service/src/modules/blogs/blogs.routes.ts`
- [Comments and replies](https://github.com/techaccecho/backend-service/blob/main/apps/blog-service/src/modules/comments/comments.routes.ts): `apps/blog-service/src/modules/comments/comments.routes.ts`
- [Engagement rules](https://github.com/techaccecho/backend-service/blob/main/apps/blog-service/src/modules/rules-of-engagement/rules-of-engagement.routes.ts): `apps/blog-service/src/modules/rules-of-engagement/rules-of-engagement.routes.ts`
- [State API](https://github.com/techaccecho/backend-service/blob/main/apps/state-service/src/modules/state/state.routes.ts): `apps/state-service/src/modules/state/state.routes.ts`
- [Reserved game API](https://github.com/techaccecho/backend-service/tree/main/apps/game-service/src): `apps/game-service/src`

### Shared runtime

- [User routes](https://github.com/techaccecho/backend-service/blob/main/lib/starter/src/modules/auth/users.routes.ts): `lib/starter/src/modules/auth/users.routes.ts`
- [Authentication hooks](https://github.com/techaccecho/backend-service/blob/main/lib/starter/src/modules/auth/hooks/auth.hook.ts): `lib/starter/src/modules/auth/hooks/auth.hook.ts`

### Domain logic

- [Blog domain](https://github.com/techaccecho/backend-service/blob/main/lib/domain/src/blog/blog.schema.ts): `lib/domain/src/blog/blog.schema.ts`
- [Blog content](https://github.com/techaccecho/backend-service/blob/main/lib/domain/src/blog/blog-content.ts): `lib/domain/src/blog/blog-content.ts`
- [User domain](https://github.com/techaccecho/backend-service/blob/main/lib/domain/src/user/user.schema.ts): `lib/domain/src/user/user.schema.ts`
- [API definitions](https://github.com/techaccecho/backend-service/blob/main/lib/domain/src/api/api.schema.ts): `lib/domain/src/api/api.schema.ts`
- [ARG rules engine](https://github.com/techaccecho/backend-service/blob/main/apps/state-service/src/modules/state/ArgRulesEngine.ts): `apps/state-service/src/modules/state/ArgRulesEngine.ts`
- [Progress projection](https://github.com/techaccecho/backend-service/blob/main/apps/state-service/src/modules/state/ArgRulesEngine.ts): `apps/state-service/src/modules/state/ArgRulesEngine.ts`

### Data layer

- [Convex database](https://github.com/techaccecho/backend-service/blob/main/lib/data/convex/schema.ts): `lib/data/convex/schema.ts`
- [Blog records](https://github.com/techaccecho/backend-service/blob/main/lib/data/convex/blogs.ts): `lib/data/convex/blogs.ts`
- [User records](https://github.com/techaccecho/backend-service/blob/main/lib/data/convex/users.ts): `lib/data/convex/users.ts`
- [Step definitions](https://github.com/techaccecho/backend-service/blob/main/lib/data/convex/stepDefinitions.ts): `lib/data/convex/stepDefinitions.ts`
- [Player state](https://github.com/techaccecho/backend-service/blob/main/lib/data/convex/argPlayerStates.ts): `lib/data/convex/argPlayerStates.ts`

### Other components

- **API clients**

## Connections

- API clients → Admin API: manage records (evidence: `README.md`)
- API clients → Blog API: use blogs (evidence: `README.md`)
- API clients → Comments and replies: comment and reply (evidence: `README.md`)
- API clients → Auth service: authenticate (evidence: `README.md`)
- API clients → State API: track progression (evidence: `README.md`)
- API clients → Reserved game API: future game use (evidence: `README.md`)
- User routes → Authentication hooks: uses hooks (evidence: `lib/starter/src/modules/auth/users.routes.ts`)
- Blog API → Blog domain: uses blog schemas (evidence: `apps/blog-service/src/modules/blogs/blogs.routes.ts`)
- Blog API → Blog content: content operations
- Comments and replies → Blog domain: returns blog data (evidence: `apps/blog-service/src/modules/comments/comments.routes.ts`)
- Admin API → API definitions: API management
- User routes → User domain: uses user commands (evidence: `lib/starter/src/modules/auth/users.routes.ts`)
- User domain → User records: queries user data
- Blog API → Blog records: reads and writes blogs
- Blog records → Convex database: persists records
- User records → Convex database: persists records
- State API → ARG rules engine: evaluates progression (evidence: `apps/state-service/src/modules/state/state.routes.ts`)
- State API → Step definitions: loads step definitions (evidence: `README.md`)
- State API → Player state: reads and updates state (evidence: `README.md`)
- ARG rules engine → Progress projection: computes payload (evidence: `apps/state-service/src/modules/state/ArgRulesEngine.ts`)
- Step definitions → Convex database: stores definitions
- Player state → Convex database: stores progression
