Bio Management System
Relevant source files
The following files were used as context for generating this wiki page:
- apps/api/spec/bio.md
- apps/api/src/modules/bio/application/bio.service.ts
- apps/api/src/modules/bio/domain/bio.ts
- apps/api/test/modules/bio/application/bio.service.test.ts
- apps/api/test/infrastructure/http/bio.router.test.ts
- apps/web/src/features/bio/bio.schema.ts
- apps/api/test/modules/bio/infrastructure/bio.pg-repository.test.ts
The Bio Management System manages user profile information, including handles, names, headlines, and descriptions. It provides both public read access for personal websites and private write access for bio owners. The system is exposed through Model Context Protocol (MCP) tools and a standard HTTP API.
Sources: apps/api/spec/bio.md:1-12, apps/web/spec/web.md:1-5
Core Architecture
The system follows a layered architecture comprising a domain model, application services, and multiple interface adapters (HTTP and MCP).
Domain Model
The Bio class represents the core entity. It enforces data integrity by requiring all fields to be non-blank.
The domain model ensures that every bio contains a unique identifier, a user association, and descriptive text fields.
Sources: apps/api/src/modules/bio/domain/bio.ts:1-36
Data Flow
Requests flow from interface adapters to the BioService, which interacts with the BioRepository for persistence.
Data Structures and Validation
The system enforces strict validation rules on bio inputs to ensure consistency and prevent collisions.
Bio Fields
| Field | Type | Constraint | Description |
|---|---|---|---|
handle | string | Max 60 chars, lowercase, slug format | Unique public identifier for the bio. |
name | string | Max 100 chars, non-blank | The full name of the user. |
headline | string | Max 200 chars, non-blank | A short professional summary. |
about | string | Max 5000 chars, non-blank | Detailed biographical information. |
Sources: apps/api/spec/bio.md:15-22, apps/api/src/modules/bio/domain/bio.ts:28-35, apps/web/src/features/bio/bio.schema.ts:3-7
Validation Rules
- Slug Format: Handles must contain only lowercase letters, digits, and hyphens (hyphens cannot be leading or trailing).
- Uniqueness: A
handlemust be unique across all users. - Ownership: A user can only own one bio. Attempts to create a second bio result in an
ALREADY_EXISTSerror. - Trimming: All string inputs are trimmed before validation or storage.
Sources: apps/api/spec/bio.md:46-64, apps/api/src/modules/bio/application/bio.service.ts:39-65
Interface Definitions
MCP Tools
The system registers three tools for use with MCP-compatible clients:
get_bio: Public tool to retrieve bio details by handle.create_bio: Private tool for users to establish their bio.update_bio: Private tool for users to modify their existing bio.
Sources: apps/api/spec/bio.md:10-12, apps/api/test/modules/bio/interface/bio.tool.integration.test.ts:38-44
HTTP API
A public endpoint provides JSON access for web frontends.
- Endpoint:
GET /bio/:handle - Success (200): Returns
{ name, headline, about }. - Failure (404): Returns
BIO_NOT_FOUNDif the handle does not exist.
Sources: apps/api/spec/bio.md:38-43, apps/api/test/infrastructure/http/bio.router.test.ts:38-55
Operational Logic
Creating and Updating Bios
The BioService manages the logic for writing data. It generates unique IDs for new bios and checks for handle availability.
Error States
The system uses specific error codes defined in @thoth/utils/error-codes.
| Error Code | HTTP Status | Trigger Condition |
|---|---|---|
BIO_NOT_FOUND | 404 | Handle or ID does not exist in the database. |
BIO_HANDLE_TAKEN | 409 | The requested handle is already owned by another user. |
BIO_ALREADY_EXISTS | 409 | The caller already owns a bio record. |
INVALID_INPUT | 400 | Validation fails (e.g., blank fields or invalid slug). |
Sources: apps/api/spec/bio.md:25-36, apps/api/src/modules/bio/application/bio.service.ts:52-65
Summary
The Bio Management System provides a robust mechanism for users to define their public identity within the Thoth platform. It enforces strict validation and ownership rules, ensuring that bios are unique and properly formatted for display on the owner's public website.