@clidey/dory 0.1.0

package/README.md

@@ -0,0 +1,185 @@
+<div align="center">
+  <img src="./assets/dory_logo.png" alt="Dory Logo" width="200" />
+</div>
+
+# Dory
+
+> 🐟 A lightweight static site generator for technical documentation.
+
+Dory is a lightweight static site generator built for developers who want fast, clean, and customizable documentation — without the overhead of server-side rendering, complex CI/CD setups, or cloud-specific constraints.
+
+Built with [Preact](https://preactjs.com/), [Vite](https://vitejs.dev/), [Tailwind CSS](https://tailwindcss.com/), [Mermaid](https://mermaid.js.org/), and [TypeScript](https://www.typescriptlang.org/).
+
+---
+
+## 🚀 Why Dory?
+
+We created Dory while building a documentation platform and getting frustrated by bloated frameworks, slow build times, and cryptic deployment errors.
+
+Dory is:
+
+- 🧠 **Simple** — Drop in `.mdx` files and configure one `dory.json`.
+- ⚡ **Fast** — Instant hot reload in dev, quick static builds for prod.
+- 🌐 **Portable** — No SSR, no lock-in, deploy anywhere.
+- 🧩 **Flexible** — Hackable theme, readable codebase, minimal magic.
+
+---
+
+## ✨ Features
+
+- 📄 Write docs in `.mdx` (Markdown + JSX)
+- 🧭 Configure site structure with a single `dory.json`
+- 🧪 Built-in components for layout, navigation, and code highlighting
+- 🔁 Instant hot-reload during development
+- 📊 Mermaid support for diagrams and flows
+- 🎨 Customizable via Tailwind and minimal theme overrides
+- 🌍 Deploy to Netlify, Vercel, S3, GitHub Pages — your call
+- 🌐 HTTP client for testing API endpoints (automatic inference from openapi.json)
+
+---
+
+## 📦 CLI Installation
+
+Install Dory globally to use the CLI tool:
+
+```bash
+npm install -g dory
+```
+
+### CLI Usage
+
+Once installed, you can use the `dory` command:
+
+#### `dory build`
+Builds your documentation site:
+- Checks for `dory.json` in current directory
+- Clears and prepares the `docs` folder
+- Copies configuration to `docs` folder
+- Runs the build process
+- Creates `dist` folder with build output
+
+```bash
+dory build
+```
+
+#### `dory preview`
+Previews the built documentation site:
+- Requires `dist` folder (run `dory build` first)
+- Starts a local preview server
+
+```bash
+dory preview
+```
+
+#### `dory help`
+Shows CLI usage information:
+
+```bash
+dory help
+```
+
+---
+
+## 🧑‍💻 Development Setup
+
+Follow these steps to set up and preview the documentation locally, as well as build a static site for deployment.
+
+### 1️⃣ Clone the Repository
+
+Clone the repository to your local machine:
+
+```bash
+git clone https://github.com/clidey/dory.git
+cd dory
+````
+
+---
+
+### 2️⃣ Install Dependencies
+
+Install all required dependencies using `pnpm`:
+
+```bash
+pnpm install
+```
+
+Make sure you have `pnpm` installed. If not, you can install it via:
+
+```bash
+npm install -g pnpm
+```
+
+---
+
+### 3️⃣ Copy Documentation Content
+
+Copy your existing documentation into the `./docs` directory:
+
+```bash
+rm -rf ./docs
+cp ../wherever-the-docs-are/. ./docs
+```
+
+> Replace `../wherever-the-docs-are/` with the actual path to your documentation source files.
+
+---
+
+### 4️⃣ Start Development Server
+
+Start the development server to preview the documentation locally:
+
+```bash
+pnpm run dev
+```
+
+This will launch a local server (typically at `http://localhost:3000`) where you can preview and edit your documentation in real-time.
+
+---
+
+### 5️⃣ Build Static Site for Production
+
+To generate a static version of the site for production deployment:
+
+```bash
+pnpm run build
+```
+
+This will create a `dist` directory containing the fully built static site, ready to be served.
+
+---
+
+## 🐳 Docker Deployment (Optional)
+
+You can also build and run the static site inside a Docker container using Nginx:
+
+### Build Docker Image
+
+```bash
+docker build -f k8s/Dockerfile --tag docs:1.0.0 .
+```
+
+### Run Docker Container
+
+```bash
+docker run -it -p 8080:80 docs:1.0.0
+```
+
+> The site will be available at `http://localhost:8080` inside your browser.
+
+---
+
+## 📂 Notes
+
+* `pnpm run build` creates the static site inside the `dist` folder, which can be served using any static file server.
+* The Docker image uses Nginx to serve the contents of the `dist` folder.
+
+
+## 🔮 Roadmap
+
+We’re actively improving Dory. Here’s what’s on deck:
+
+* [ ] 📚 **Full Documentation** — comprehensive guides, API docs, and examples
+* [ ] 🎨 **Themes** — full theming support with a flexible theme API
+* [ ] 🌐 **Multi-language Support** — internationalization (i18n) & localization (l10n)
+* [ ] 🚀 **GraphQL Client** — integrated GraphQL playground and client support
+* [ ] 🔄 **WebSocket Client** — built-in WebSocket utilities for real-time API demos

package/SECURITY.md

@@ -0,0 +1,11 @@
+# Security Policy
+
+## Supported Versions
+
+Currently the latest version of Dory is supported. We advise you to upgrade whenever possible to receive the latest security updates.
+
+## Reporting a Vulnerability
+
+Please use the repo's Report A Vulnerability option to report.
+
+The team will send a response indicating the next steps in handling your report. After the initial reply to your report, the security team will keep you informed of the progress towards a fix, and may ask for additional information or guidance.

package/bin/dory.js

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+
+import { execSync } from 'child_process';
+import { existsSync, rmSync, mkdirSync, cpSync, readFileSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url'
+import http from 'http';
+import sirv from 'sirv';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const commands = {
+  build: () => {
+    console.log('🏗️  Starting Dory build...');
+    
+    // Check if dory.json exists in current directory
+    const currentDir = process.cwd();
+    const doryConfigPath = resolve(currentDir, 'dory.json');
+    
+    if (!existsSync(doryConfigPath)) {
+      console.error('❌ dory.json not found in current directory');
+      process.exit(1);
+    }
+    
+    // Read and validate dory.json
+    try {
+      const config = JSON.parse(readFileSync(doryConfigPath, 'utf8'));
+      console.log(`📋 Using config: ${config.name || 'Unnamed project'}`);
+    } catch (error) {
+      console.error('❌ Invalid dory.json file:', error.message);
+      process.exit(1);
+    }
+    
+    // Clear and prepare docs folder
+    const docsDir = resolve(currentDir, 'docs');
+    if (existsSync(docsDir)) {
+      console.log('🧹 Clearing docs folder...');
+      rmSync(docsDir, { recursive: true, force: true });
+    }
+    mkdirSync(docsDir, { recursive: true });
+    
+    // Copy dory.json to docs folder
+    cpSync(doryConfigPath, resolve(docsDir, 'dory.json'));
+    console.log('📄 Copied dory.json to docs folder');
+    
+    // Run the build command
+    console.log('⚡ Running build command...');
+    try {
+      execSync('npm run build', { stdio: 'inherit', cwd: __dirname });
+    } catch (error) {
+      console.error('❌ Build failed:', error.message);
+      process.exit(1);
+    }
+    
+    // Check if dist folder was created
+    const distDir = resolve(__dirname, '..', 'dist');
+    if (existsSync(distDir)) {
+      console.log('✅ Build completed successfully!');
+      console.log(`📦 Build output available in: ${distDir}`);
+      console.log('📋 Moving build output to current directory...');
+      cpSync(distDir, resolve(currentDir, 'dist'), { recursive: true });
+      console.log(`📦 Build output moved to: ${resolve(currentDir, 'dist')}`);
+    } else {
+      console.log('⚠️  Build completed but no dist folder found');
+    }
+    rmSync(distDir, { recursive: true, force: true });
+  },
+
+  preview: () => {
+    console.log('👀 Starting Dory preview...');
+    const currentDir = process.cwd();
+    const distDir = resolve(currentDir, 'dist');
+    const port = process.env.PORT || 3000;
+
+    const serve = sirv(distDir, {
+      dev: false,
+      single: true,
+      etag: true,
+      gzip: true,
+      brotli: true,
+    });
+
+    const server = http.createServer((req, res) => {
+      serve(req, res);
+    });
+
+    server.listen(port, () => {
+      console.log(`🚀 Serving Dory at http://localhost:${port}`);
+    });
+  },
+
+  help: () => {
+    console.log(`
+🐟 Dory CLI - Documentation Build Tool
+
+Usage:
+  dory <command>
+
+Commands:
+  build     Build the documentation site
+            - Requires dory.json in current directory
+            - Clears and copies to docs folder
+            - Runs build command
+            - Creates dist folder with build output
+            
+  preview   Preview the built documentation site
+            - Requires dist folder (run build first)
+            - Starts preview server
+            
+  help      Show this help message
+
+Examples:
+  dory build    # Build the documentation
+  dory preview  # Preview the built site
+`);
+  }
+};
+
+// Parse command line arguments
+const command = process.argv[2];
+
+if (!command || command === 'help' || command === '--help' || command === '-h') {
+  commands.help();
+} else if (commands[command]) {
+  commands[command]();
+} else {
+  console.error(`❌ Unknown command: ${command}`);
+  console.log('Run "dory help" for usage information');
+  process.exit(1);
+}

package/docs/README.md

@@ -0,0 +1,2 @@
+# genie-internal
+Created via Docucod

package/docs/configuration/app-settings/feature-flags.mdx

@@ -0,0 +1,157 @@
+---
+title: 'Feature Flags'
+description: 'Manage and understand feature flags affecting the application behavior.'
+---
+
+# Feature Flags
+
+## Purpose and Scope
+
+The Feature Flags module provides a centralized mechanism to enable or disable specific features within the Genie application dynamically. This approach allows controlled rollout, testing, and gradual adoption of new functionalities without deploying new code versions.
+
+This module primarily parses and validates feature flag configurations from environment variables and exposes them for use throughout the web and API services.
+
+## Technical Overview
+
+Feature Flags are defined and validated using the `zod` schema validation library to ensure that flag values comply with expected types. Flags can generally be boolean or strings convertible to booleans (`"true"`), permitting flexibility in how environment variables are specified.
+
+The parsing logic safely attempts to read environment variables, falling back to an empty object on failure and capturing exceptions with Sentry for monitoring.
+
+### Key Locations
+
+- **Web client feature flags:** Defined and parsed in `apps/web/src/utils/feature-flags.ts`.
+- **API service feature flags:** Defined under API config schemas in `apps/api/src/config/schemas/index.ts`.
+
+
+## Core Concepts and Responsibilities
+
+- **Feature Flags Schema:** A set of typed mappings that describe each flag's expected type and optional presence.
+- Flags can be a boolean or a string (`"true"` interpreted as `true`) or undefined.
+- Certain flags have additional typed definitions such as arrays, e.g., `DEMAND_PLANNER_SHOP_ALLOW_LIST` which is an optional array of strings.
+
+- **Error Handling:** Parsing errors are logged to Sentry via `Sentry.captureException(error)` to facilitate early detection of misconfiguration.
+
+- **Environmental Scope:** Flags are read from environment variables prefixed with `NEXT_PUBLIC_FEATURE_FLAGS` for frontend exposure or `FEATURE_FLAGS` for the backend.
+
+- **Security and Scope:** Flags must be explicitly defined in environment configuration, preventing undefined or unexpected flags from being used.
+
+## Code Structure
+
+### `apps/web/src/utils/feature-flags.ts`
+
+This file implements the feature flag parsing logic for the web frontend.
+
+- `flagSchema`: Accepts either a boolean or a string representing booleans and transforms the string to a boolean.
+- `featureFlagsSchema`: Defines known feature flags such as `UI_PAGE`, `DEMAND_PLANNER`, `MOV`, `PAYMENT_TERMS`, and others. Some flags are booleans, others arrays of strings.
+- `parseFeatureFlags()`:
+  - Attempts to JSON parse the environment variable `NEXT_PUBLIC_FEATURE_FLAGS`.
+  - Validates it against the schema.
+  - On error, logs to Sentry and returns an empty object.
+- `FEATURE_FLAGS`: Exported constant representing the parsed flags for app-wide consumption.
+
+```ts
+import { z } from "zod";
+import * as Sentry from "@sentry/nextjs";
+
+const flagSchema = z.union([
+  z.boolean(),
+  z.string().transform((val) => val === "true")
+]).optional();
+
+const featureFlagsSchema = z.object({
+  UI_PAGE: flagSchema,
+  DEMAND_PLANNER: flagSchema,
+  DEMAND_PLANNER_SHOP_ALLOW_LIST: z.array(z.string()).optional(),
+  MOV: flagSchema,
+  PAYMENT_TERMS: flagSchema,
+  MANUAL_STATUS: flagSchema,
+  REPORTS_ALERTS: flagSchema,
+  PAYMENTS_PAGE: flagSchema,
+});
+
+type FeatureFlags = z.infer<typeof featureFlagsSchema>;
+
+const parseFeatureFlags = (): FeatureFlags => {
+  try {
+    return featureFlagsSchema.parse(
+      JSON.parse(process.env.NEXT_PUBLIC_FEATURE_FLAGS || "{}")
+    );
+  } catch (error) {
+    Sentry.captureException(error);
+    return {};
+  }
+};
+
+export const FEATURE_FLAGS = parseFeatureFlags();
+```
+
+### `apps/api/src/config/schemas/index.ts`
+
+This file extends feature flag support within the API backend.
+
+- The API uses a similar schema (`featureFlagSchema`) that accepts booleans or strings convertible to booleans.
+- `featureFlagsSchema` is defined but currently empty (`z.object({} satisfies Record<string, typeof featureFlagSchema>)`).
+- The `FEATURE_FLAGS` environment variable is parsed and coerced to a string, then JSON parsed and validated.
+
+The config schema merges the feature flags, along with many other env vars, into a consolidated validation schema.
+
+```ts
+const featureFlagSchema = z.union([
+  z.boolean(),
+  z.string().transform((value) => value === "true")
+]).optional();
+
+const featureFlagsSchema = z.object(
+  {} satisfies Record<string, typeof featureFlagSchema>
+);
+
+export type FeatureFlags = z.infer<typeof featureFlagsSchema>;
+
+export const configSchema = z.object({
+  // ... other config fields ...
+  FEATURE_FLAGS: z.coerce.string().optional().transform((jsonString = "{}") =>
+    featureFlagsSchema.parse(JSON.parse(jsonString))
+  ),
+  // ... other config fields ...
+}).merge(databaseConfigSchema).strip();
+```
+
+## Environment & Configuration
+
+### Environment Variables
+
+- `NEXT_PUBLIC_FEATURE_FLAGS` (frontend): JSON string representing flags.
+- `FEATURE_FLAGS` (API backend): JSON string representing flags.
+
+Example environment value for frontend (simplified):
+
+```json
+{
+  "UI_PAGE": true,
+  "DEMAND_PLANNER": "true",
+  "DEMAND_PLANNER_SHOP_ALLOW_LIST": ["shop1", "shop2"],
+  "MOV": false
+}
+```
+
+The environment variable must be valid JSON and correctly typed for each feature flag.
+
+## Integration & System Boundaries
+
+- **Web UI:** Uses parsed `FEATURE_FLAGS` to enable/disable UI features.
+- **API:** Reads feature flags from environment on startup to alter backend behavior.
+- **Error Logging:** Parsing issues send errors to Sentry for diagnosis.
+
+## Observability & Error Handling
+
+- Parsing errors of feature flags are monitored via Sentry.
+- Apps fall back gracefully to default empty flags on error, ensuring stability.
+
+## Summary
+
+This feature flags module provides a robust, type-safe approach to managing application features dynamically through environment configuration. It ensures flags are validated on startup and exposes them as constants for consistent use across frontend and backend components.
+
+## References
+
+- [Feature Flags in Web Frontend](apps/web/src/utils/feature-flags.ts)
+- [Feature Flags in API Config](apps/api/src/config/schemas/index.ts)

package/docs/configuration/app-settings/user-settings.mdx

@@ -0,0 +1,201 @@
+---
+title: 'User and Team Settings'
+description: 'Configuration of user preferences, team settings, saved views, and insights settings.'
+---
+
+## User and Team Settings - Internal Developer Documentation
+
+### 1. Purpose and Scope
+
+This module handles **user and team settings management** within the Genie application, enabling users to configure team-wide preferences, manage memberships, and control notifications. It provides REST API endpoints to update and retrieve team general settings, insights settings, shop settings, and manage invitations and team members.
+
+The module's responsibilities include:
+- CRUD operations on team settings (general, insights, shop).
+- Managing team member invitations and acceptance.
+- Deactivating users from a team.
+- Querying team membership and invitation status.
+- Managing user notification preferences.
+
+It acts as a boundary between frontend clients and backend services managing persistent storage and business logic related to teams and user contexts.
+
+### 2. Technical Overview
+
+The main components involved are:
+
+- **TeamsController** (`apps/api/src/user-management/controllers/teams.controller.ts`): API entrypoint defining HTTP routes for team settings and team user management.
+- **SettingsService** (`apps/api/src/user-management/services/settings.service.ts`): Business logic for retrieving and updating team settings.
+- **TeamsService** (`apps/api/src/user-management/services/teams.service.ts`): Business logic for user and invitation management within teams.
+- **UserContextController** (`apps/api/src/user-management/controllers/user-context.controller.ts`): Manages retrieval of user context and notification preferences.
+
+The module leverages **NestJS** for structuring controllers and services and **TypeORM** for database interactions with `TeamEntity`, `UserEntity`, and `MemberInvitationEntity`.
+
+Dependencies include:
+- Shared DTOs and schemas from `@genie/shared` for payload validation.
+- Zod validation pipes for input validation.
+- JWT service for token handling during invitation acceptance.
+
+#### Architectural Pattern:
+- The system follows an **MVC-style architecture** where Controllers handle HTTP requests, delegate to Services for business logic, and Services interact with entities via repositories.
+
+### 3. Core Concepts and Responsibilities
+
+- **Team Settings** are divided into:
+  - **General Settings**: Business name, contact info, VAT, and address.
+  - **Insights Settings**: Sales period days, stock levels, and grading strategy parameters.
+  - **Shop Settings**: Currency and timezone.
+
+- **Users and Invitations**:
+  - Invitations are managed as entities with statuses (Pending, Accepted, Expired).
+  - An invitation can be sent, accepted with validation and token generation, or expired.
+  - Only Admin users can deactivate users.
+
+- **Notification Settings**:
+  - Stored as JSON config inside team entity under `notifications`.
+  - Users can retrieve and update their notification preferences.
+
+- **Error Handling**:
+  - If requests come from users with no team association, `GenieException` with "User not in a team" message is thrown.
+  - Role-based authorization on critical operations like user deactivation.
+
+- **Security**:
+  - Invitation acceptance requires a valid code (invitation ID) and checks for expiration.
+  - JWT tokens are issued upon invitation acceptance.
+
+### 4. Code Structure
+
+| File | Description |
+|-------|-------------|
+| `teams.controller.ts` | API endpoints for team settings and user management (send invitations, deactivate users, retrieve members) |
+| `settings.service.ts` | Implements logic to get and update team settings in the DB, including insights and shop settings |
+| `teams.service.ts` | Handles user retrieval, invitations, notification states, team user management, and tokenized invitation acceptance |
+| `user-context.controller.ts` | API endpoints to get user context and manage user notification preferences |
+| `team.entity.ts` | Defines Team entity schema, including settings fields and onboarding states |
+| `user.entity.ts` | Defines User entity schema and relations to team |
+
+
+#### Example snippet from TeamsController showing settings update endpoint:
+```ts
+@Put("settings")
+@HttpCode(204)
+async updateTeamSettings(@Request() { user }: RequestWithUser, @Body(new ZodValidationPipe(teamSettingsDtoSchema)) settings: TeamSettingsDto) {
+  if (!user.teamId) throw new GenieException("User not in a team");
+  await this.settingsService.updateTeamSettings(user.teamId, settings);
+}
+```
+
+### 5. API and Interfaces
+
+#### TeamsController Endpoints Summary
+
+| Endpoint                      | Method | Description                                         | Req. Auth | Input (DTO)                          | Output                   |
+|-------------------------------|--------|-----------------------------------------------------|-----------|-------------------------------------|--------------------------|
+| `/teams/settings`              | PUT    | Update complete team settings                      | Yes       | `TeamSettingsDto`                    | 204 No Content           |
+| `/teams/settings/general`      | PUT    | Update team general settings                        | Yes       | `TeamGeneralSettingsDto`             | 204 No Content           |
+| `/teams/settings/general`      | GET    | Get team general settings                           | Yes       | -                                   | `TeamGeneralSettingsDto` |
+| `/teams/settings/insights`     | PUT    | Update team insights settings                       | Yes       | `InsightsSettingsDto`                 | 204 No Content           |
+| `/teams/settings/insights`     | GET    | Get team insights settings                          | Yes       | -                                   | `InsightsSettingsDto`      |
+| `/teams/settings/shop`         | GET    | Get team shop settings (currency, timezone)        | Yes       | -                                   | `GetShopSettingsResponseDto` |
+| `/teams/members`               | GET    | Get all team members and invitations               | Yes       | -                                   | `GetTeamUsersInfoResponseDto` |
+| `/teams/send-invitations`      | POST   | Send invitations to new members                     | Yes       | `SendInvitationsRequestDto`          | `SendInvitationsResponseDto` |
+| `/teams/user/:id/deactivate`  | PATCH  | Deactivate a user (admin-only)                      | Yes       | -                                   | 204 No Content           |
+| `/teams/invitations/:email`    | DELETE | Remove an invitation by email                       | Yes       | -                                   | 204 No Content           |
+| `/teams/accept-invitation`     | POST   | Accept invitation and obtain auth token            | No        | `AcceptInvitationRequestDto`         | `{ token: string }`       |
+
+#### UserContextController Endpoints
+
+| Endpoint                | Method | Description                    | Auth   | Input                   | Output                         |
+|-------------------------|--------|--------------------------------|--------|-------------------------|-------------------------------|
+| `/user-context`          | GET    | Get current user context       | Yes    | -                       | `GetUserContextResponseDto`   |
+| `/user-context/notifications` | GET    | Get user/team notification prefs | Yes    | -                       | `UserNotificationsSchema`      |
+| `/user-context/notifications` | PUT    | Update notification preferences | Yes    | `UserNotificationsSchema` | 204 No Content                 |
+
+#### API Validation
+- All request bodies are validated using `ZodValidationPipe` based on shared DTO schemas.
+- User authorization checks confirm user belongs to a team before proceeding.
+
+#### Failure Modes
+- Throws `GenieException` with clear messages for unauthorized or invalid operations, e.g. "User not in a team", "Only team admins can remove users".
+- Invitation acceptance fails with `ForbiddenException` for invalid or expired codes.
+
+### 6. Environment & Configuration
+
+- Uses environment variables for:
+  - Intercom secret (`INTERCOM_IDENTITY_VERIFICATION_SECRET`) for generating user hashes.
+  - Team integration tokens for Mantle subscription management.
+
+- Slack app token and channel IDs are used indirectly via injected `SlackService` for notifications when related to teams.
+
+- Team settings updates impact DB table `team` via TypeORM repository.
+
+- JWT secret utilized by `JwtService` for signing tokens on invitation acceptance.
+
+### 7. Testing, Monitoring, and Deployment
+
+- Standard NestJS testing practices apply. Unit and integration tests should cover:
+  - Controller endpoint authorization and validation.
+  - Service method's DB interactions and error handling.
+
+- Observability:
+  - Errors throw `GenieException` which integrates with centralized error handling.
+  - Logging and tracing occur in related services (not detailed here).
+
+- Deployment follows standard service lifecycle as per NestJS backend.
+
+### 8. Troubleshooting & Known Issues
+
+- Common failure if the user is not assigned to a team is consistently checked in controllers.
+- Admin-only restrictions on deactivation ensure minimal privilege violations.
+- Expired or invalid invitation codes are handled explicitly with meaningful exceptions.
+
+### 9. Style and Tone Guidelines
+
+- Terminology consistent with codebase entities: "team", "user", "invitation", "settings".
+- Methods first check authorization and preconditions, then perform updates.
+- API uses HTTP 204 status for successful PUT/PATCH requests with no response body.
+
+---
+
+## Mermaid Diagram: Teams and User Settings Module Architecture
+
+```mermaid
+flowchart TD
+  subgraph API Layer
+    TeamsController["TeamsController<br/>(HTTP API)" ]:::api
+    UserContextController["UserContextController<br/>(User Context API)"]:::api
+  end
+
+  subgraph Services Layer
+    SettingsService["SettingsService<br/>Team Settings Logic"]:::service
+    TeamsService["TeamsService<br/>User & Invitations Logic"]:::service
+  end
+
+  subgraph Persistence Layer
+    TeamEntity["TeamEntity<br/>(Postgres DB)"]:::db
+    UserEntity["UserEntity<br/>(Postgres DB)"]:::db
+    MemberInvitationEntity["MemberInvitationEntity<br/>(Postgres DB)"]:::db
+  end
+
+  %% Relationships
+  TeamsController -->|calls| SettingsService
+  TeamsController -->|calls| TeamsService
+  UserContextController -->|calls| TeamsService
+
+  SettingsService -->|reads/writes| TeamEntity
+  TeamsService -->|reads/writes| UserEntity
+  TeamsService -->|reads/writes| TeamEntity
+  TeamsService -->|reads/writes| MemberInvitationEntity
+
+  %% Classes styles
+  classDef api fill:#f9f,stroke:#333,stroke-width:1px,color:#000
+  classDef service fill:#bbf,stroke:#333,stroke-width:1px,color:#000
+  classDef db fill:#bfb,stroke:#060,stroke-width:1px,color:#060
+
+  %% Click events
+  click TeamsController "apps/api/src/user-management/controllers/teams.controller.ts"
+  click UserContextController "apps/api/src/user-management/controllers/user-context.controller.ts"
+  click SettingsService "apps/api/src/user-management/services/settings.service.ts"
+  click TeamsService "apps/api/src/user-management/services/teams.service.ts"
+  click TeamEntity "apps/api/src/user-management/entities/team.entity.ts"
+  click UserEntity "apps/api/src/user-management/entities/user.entity.ts"
+  click MemberInvitationEntity "apps/api/src/user-management/entities/member-invitation.entity.ts"
+```