# zwiqler94/username-generator architecture

> Architecture diagram of the GitHub repository zwiqler94/username-generator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zwiqler94/username-generator
- Repository: https://github.com/zwiqler94/username-generator

## Overview

The product is a Firebase-backed username-generation service. Clients obtain an App Check token through either the callable helper or authenticated HTTP token route, then submit words and optional specials to the HTTP API; the API validates and guards the request, looks up thesaurus terms, filters and combines words, and returns unique usernames. The controller, routing, and middleware are distinct internal layers. Relationships shown are supported by the excerpts or README; unsampled implementation details are not expanded.

Main entry points: [`functions/src/controllers/usernames.controller.ts`](https://github.com/zwiqler94/username-generator/blob/main/functions/src/controllers/usernames.controller.ts) (Username Generator), [`functions/src/server.ts`](https://github.com/zwiqler94/username-generator/blob/main/functions/src/server.ts) (Express Routes), [`functions/src/middleware/auth.middleware.ts`](https://github.com/zwiqler94/username-generator/blob/main/functions/src/middleware/auth.middleware.ts) (Token HTTP Route), [`functions/src/middleware/general.middleware.ts`](https://github.com/zwiqler94/username-generator/blob/main/functions/src/middleware/general.middleware.ts) (API Middleware)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_http_api["HTTP API Functions<br/>[index.ts]"]
  node_express_app["Express Routes<br/>[server.ts]"]
  node_username_validator["Request Validator"]
end

subgraph group_generation["Username Generation"]
  node_generator["Username Generator"]
  node_bad_words["Profanity Terms<br/>[bad-words.ts]"]
  node_default_words["Fallback Words<br/>[default-words.ts]"]
  node_thesaurus_model["Thesaurus Model<br/>[thesaurus.model.ts]"]
end

subgraph group_security["Token and Security"]
  node_shared_middleware["API Middleware"]
  node_auth_routes["Token HTTP Route<br/>[auth.middleware.ts]"]
  node_auth_validator["Auth Validator<br/>[auth.validator.ts]"]
end

subgraph group_callable["Callable Token Helper"]
  node_callable_function["Callable Token Function<br/>[index.ts]"]
end

node_client(("Client"))
node_thesaurus["Merriam-Webster Thesaurus"]
node_firebase_auth["Firebase Auth"]
node_app_check["Firebase App Check"]

node_client -->|"calls API"| node_http_api
node_http_api -->|"serves app"| node_express_app
node_express_app -->|"sets up"| node_shared_middleware
node_express_app -->|"mounts routes"| node_auth_routes
node_express_app -->|"validates request"| node_username_validator
node_express_app -->|"routes to"| node_generator
node_shared_middleware -->|"verifies token"| node_app_check
node_generator -->|"filters terms"| node_bad_words
node_generator -->|"uses fallback"| node_default_words
node_generator -->|"checks results"| node_thesaurus_model
node_generator -->|"looks up terms"| node_thesaurus
node_generator -->|"returns usernames"| node_client
node_auth_routes -->|"validates token"| node_auth_validator
node_auth_routes -->|"checks identity"| node_shared_middleware
node_shared_middleware -->|"verifies ID token"| node_firebase_auth
node_auth_routes -->|"creates token"| node_app_check
node_client -->|"requests token"| node_auth_routes
node_client -->|"invokes callable"| node_callable_function
node_callable_function -->|"creates token"| node_app_check
node_callable_function -->|"returns token"| node_client

click node_http_api "https://github.com/zwiqler94/username-generator/blob/main/functions/src/index.ts"
click node_express_app "https://github.com/zwiqler94/username-generator/blob/main/functions/src/server.ts"
click node_shared_middleware "https://github.com/zwiqler94/username-generator/blob/main/functions/src/middleware/general.middleware.ts"
click node_username_validator "https://github.com/zwiqler94/username-generator/blob/main/functions/src/validators/username-req.validator.ts"
click node_generator "https://github.com/zwiqler94/username-generator/blob/main/functions/src/controllers/usernames.controller.ts"
click node_bad_words "https://github.com/zwiqler94/username-generator/blob/main/functions/src/constants/bad-words.ts"
click node_default_words "https://github.com/zwiqler94/username-generator/blob/main/functions/src/constants/default-words.ts"
click node_thesaurus_model "https://github.com/zwiqler94/username-generator/blob/main/functions/src/models/thesaurus.model.ts"
click node_auth_routes "https://github.com/zwiqler94/username-generator/blob/main/functions/src/middleware/auth.middleware.ts"
click node_auth_validator "https://github.com/zwiqler94/username-generator/blob/main/functions/src/validators/auth.validator.ts"
click node_callable_function "https://github.com/zwiqler94/username-generator/blob/main/username-generator/src/index.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_http_api,node_express_app,node_username_validator,node_client toneBlue
class node_generator,node_bad_words,node_default_words,node_thesaurus_model toneAmber
class node_shared_middleware,node_auth_routes,node_auth_validator toneMint
class node_callable_function toneRose
class node_thesaurus,node_firebase_auth,node_app_check toneIndigo
```

## Components

### HTTP API

- [HTTP API Functions](https://github.com/zwiqler94/username-generator/blob/main/functions/src/index.ts): `functions/src/index.ts`
- [Express Routes](https://github.com/zwiqler94/username-generator/blob/main/functions/src/server.ts): `functions/src/server.ts`
- [Request Validator](https://github.com/zwiqler94/username-generator/blob/main/functions/src/validators/username-req.validator.ts): `functions/src/validators/username-req.validator.ts`

### Username Generation

- [Username Generator](https://github.com/zwiqler94/username-generator/blob/main/functions/src/controllers/usernames.controller.ts): `functions/src/controllers/usernames.controller.ts`
- [Profanity Terms](https://github.com/zwiqler94/username-generator/blob/main/functions/src/constants/bad-words.ts): `functions/src/constants/bad-words.ts`
- [Fallback Words](https://github.com/zwiqler94/username-generator/blob/main/functions/src/constants/default-words.ts): `functions/src/constants/default-words.ts`
- [Thesaurus Model](https://github.com/zwiqler94/username-generator/blob/main/functions/src/models/thesaurus.model.ts): `functions/src/models/thesaurus.model.ts`

### Token and Security

- [API Middleware](https://github.com/zwiqler94/username-generator/blob/main/functions/src/middleware/general.middleware.ts): `functions/src/middleware/general.middleware.ts`
- [Token HTTP Route](https://github.com/zwiqler94/username-generator/blob/main/functions/src/middleware/auth.middleware.ts): `functions/src/middleware/auth.middleware.ts`
- [Auth Validator](https://github.com/zwiqler94/username-generator/blob/main/functions/src/validators/auth.validator.ts): `functions/src/validators/auth.validator.ts`

### Callable Token Helper

- [Callable Token Function](https://github.com/zwiqler94/username-generator/blob/main/username-generator/src/index.ts): `username-generator/src/index.ts`

### Other components

- **Client**
- **Merriam-Webster Thesaurus**
- **Firebase Auth**
- **Firebase App Check**

## Connections

- Client → HTTP API Functions: calls API (evidence: `README.md`)
- HTTP API Functions → Express Routes: serves app (evidence: `functions/src/index.ts`)
- Express Routes → API Middleware: sets up (evidence: `functions/src/server.ts`)
- Express Routes → Token HTTP Route: mounts routes (evidence: `functions/src/server.ts`)
- Express Routes → Request Validator: validates request (evidence: `functions/src/server.ts`)
- Express Routes → Username Generator: routes to (evidence: `functions/src/server.ts`)
- API Middleware → Firebase App Check: verifies token (evidence: `functions/src/middleware/general.middleware.ts`)
- Username Generator → Profanity Terms: filters terms (evidence: `functions/src/controllers/usernames.controller.ts`)
- Username Generator → Fallback Words: uses fallback (evidence: `functions/src/controllers/usernames.controller.ts`)
- Username Generator → Thesaurus Model: checks results (evidence: `functions/src/controllers/usernames.controller.ts`)
- Username Generator → Merriam-Webster Thesaurus: looks up terms (evidence: `functions/src/controllers/usernames.controller.ts`)
- Username Generator → Client: returns usernames (evidence: `README.md`)
- Token HTTP Route → Auth Validator: validates token (evidence: `functions/src/middleware/auth.middleware.ts`)
- Token HTTP Route → API Middleware: checks identity (evidence: `functions/src/middleware/auth.middleware.ts`)
- API Middleware → Firebase Auth: verifies ID token (evidence: `functions/src/middleware/general.middleware.ts`)
- Token HTTP Route → Firebase App Check: creates token (evidence: `functions/src/middleware/auth.middleware.ts`)
- Client → Token HTTP Route: requests token (evidence: `README.md`)
- Client → Callable Token Function: invokes callable (evidence: `README.md`)
- Callable Token Function → Firebase App Check: creates token (evidence: `username-generator/src/index.ts`)
- Callable Token Function → Client: returns token (evidence: `README.md`)