# binarystudioacademy/bsa-2026-promtomat architecture

> Architecture diagram of the GitHub repository binarystudioacademy/bsa-2026-promtomat, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/binarystudioacademy/bsa-2026-promtomat
- Repository: https://github.com/binarystudioacademy/bsa-2026-promtomat

## Overview

Promptomat is an intelligent prompt-search, evaluation, and autocomplete system for AI coding tools. Its product workflow centers on users organizing workspaces and prompts, searching prompt material semantically, and generating composed prompts; the backend also supports analytics, authentication, and repository bindings. The README documents a local MCP server that lets coding agents access the backend with an API token. The sampled code confirms prompt API delegation and embedding generation, persistence, and nearest-neighbor queries. Other feature links reflect documented capabilities and module boundaries; their internal call wiring was not sampled.

Main entry points: [`apps/backend/src/index.ts`](https://github.com/binarystudioacademy/bsa-2026-promtomat/blob/main/apps/backend/src/index.ts) (Backend API), [`apps/backend/src/modules/prompt-embeddings/prompt-embedding.service.ts`](https://github.com/binarystudioacademy/bsa-2026-promtomat/blob/main/apps/backend/src/modules/prompt-embeddings/prompt-embedding.service.ts) (Embedding Service), [`apps/backend/src/modules/analytics`](https://github.com/binarystudioacademy/bsa-2026-promtomat/tree/main/apps/backend/src/modules/analytics) (Prompt Analytics), [`apps/backend/src/modules/prompts/prompt.controller.ts`](https://github.com/binarystudioacademy/bsa-2026-promtomat/blob/main/apps/backend/src/modules/prompts/prompt.controller.ts) (Prompt API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_product_api["Product API"]
  node_backend["Backend API<br/>[index.ts]"]
  node_analytics["Prompt Analytics"]
end

subgraph group_prompt_domain["Prompt Search"]
  node_prompt_api["Prompt API"]
  node_prompt_services["Prompt Operations"]
  node_embeddings["Embedding Service"]
  node_embedding_repository["Vector Queries"]
  node_composed_prompts["Prompt Composition"]
end

subgraph group_workspace_domain["Workspace Data"]
  node_workspaces["Workspace Management"]
  node_contributors["Contributors"]
  node_labels["Labels"]
  node_repository_bindings["Repository Bindings"]
end

subgraph group_platform["Platform Services"]
  node_auth["Authentication"]
  node_api_tokens["API Tokens"]
  node_embedding_model["Embedding Model<br/>[embedding.ts]"]
  node_generation["Text Generation<br/>[generator.ts]"]
end

subgraph group_agent_access["Agent Access"]
  node_mcp["Local MCP Server"]
end

node_users(("Users"))
node_coding_agents(("Coding Agents"))
node_frontend["Frontend"]
node_bedrock["Bedrock"]
node_database[("PostgreSQL pgvector")]

node_users -->|"uses"| node_frontend
node_frontend -->|"calls API"| node_backend
node_coding_agents -->|"starts locally"| node_mcp
node_mcp -->|"calls API"| node_backend
node_backend -->|"authenticates"| node_auth
node_backend -->|"validates tokens"| node_api_tokens
node_backend -->|"dispatches routes"| node_prompt_api
node_prompt_api -->|"delegates"| node_prompt_services
node_prompt_services -->|"searches semantically"| node_embeddings
node_embeddings -->|"embeds text"| node_embedding_model
node_embeddings -->|"queries and stores"| node_embedding_repository
node_embedding_repository -->|"reads and writes"| node_database
node_backend -->|"dispatches routes"| node_composed_prompts
node_composed_prompts -->|"generates output"| node_generation
node_generation -.->|"invokes model"| node_bedrock
node_backend -->|"dispatches routes"| node_workspaces
node_backend -->|"dispatches routes"| node_contributors
node_backend -->|"dispatches routes"| node_labels
node_backend -->|"dispatches routes"| node_repository_bindings
node_backend -->|"dispatches routes"| node_analytics
node_workspaces -->|"persists workspace data"| node_database
node_contributors -->|"persists membership"| node_database
node_labels -->|"persists labels"| node_database
node_repository_bindings -->|"persists bindings"| node_database
node_analytics -->|"queries metrics"| node_database

click node_mcp "https://github.com/binarystudioacademy/bsa-2026-promtomat/tree/main/apps/mcp"
click node_backend "https://github.com/binarystudioacademy/bsa-2026-promtomat/blob/main/apps/backend/src/index.ts"
click node_auth "https://github.com/binarystudioacademy/bsa-2026-promtomat/tree/main/apps/backend/src/modules/auth"
click node_api_tokens "https://github.com/binarystudioacademy/bsa-2026-promtomat/tree/main/apps/backend/src/modules/api-tokens"
click node_prompt_api "https://github.com/binarystudioacademy/bsa-2026-promtomat/blob/main/apps/backend/src/modules/prompts/prompt.controller.ts"
click node_prompt_services "https://github.com/binarystudioacademy/bsa-2026-promtomat/tree/main/apps/backend/src/modules/prompts"
click node_embeddings "https://github.com/binarystudioacademy/bsa-2026-promtomat/blob/main/apps/backend/src/modules/prompt-embeddings/prompt-embedding.service.ts"
click node_embedding_model "https://github.com/binarystudioacademy/bsa-2026-promtomat/blob/main/apps/backend/src/libs/modules/embedding/embedding.ts"
click node_embedding_repository "https://github.com/binarystudioacademy/bsa-2026-promtomat/blob/main/apps/backend/src/modules/prompt-embeddings/prompt-embedding.repository.ts"
click node_composed_prompts "https://github.com/binarystudioacademy/bsa-2026-promtomat/blob/main/apps/backend/src/modules/composed-prompts/composed-prompt.service.ts"
click node_generation "https://github.com/binarystudioacademy/bsa-2026-promtomat/blob/main/apps/backend/src/libs/modules/generator/generator.ts"
click node_workspaces "https://github.com/binarystudioacademy/bsa-2026-promtomat/blob/main/apps/backend/src/modules/workspaces/workspace.controller.ts"
click node_contributors "https://github.com/binarystudioacademy/bsa-2026-promtomat/blob/main/apps/backend/src/modules/contributors/contributor.controller.ts"
click node_labels "https://github.com/binarystudioacademy/bsa-2026-promtomat/tree/main/apps/backend/src/modules/labels"
click node_repository_bindings "https://github.com/binarystudioacademy/bsa-2026-promtomat/blob/main/apps/backend/src/modules/repository-bindings/repository-binding.controller.ts"
click node_analytics "https://github.com/binarystudioacademy/bsa-2026-promtomat/tree/main/apps/backend/src/modules/analytics"

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_backend,node_analytics,node_users,node_frontend toneBlue
class node_prompt_api,node_prompt_services,node_embeddings,node_embedding_repository,node_composed_prompts,node_database toneAmber
class node_workspaces,node_contributors,node_labels,node_repository_bindings toneMint
class node_auth,node_api_tokens,node_embedding_model,node_generation toneRose
class node_mcp,node_coding_agents,node_bedrock toneIndigo
```

## Components

### Product API

- [Backend API](https://github.com/binarystudioacademy/bsa-2026-promtomat/blob/main/apps/backend/src/index.ts): `apps/backend/src/index.ts`
- [Prompt Analytics](https://github.com/binarystudioacademy/bsa-2026-promtomat/tree/main/apps/backend/src/modules/analytics): `apps/backend/src/modules/analytics`

### Prompt Search

- [Prompt API](https://github.com/binarystudioacademy/bsa-2026-promtomat/blob/main/apps/backend/src/modules/prompts/prompt.controller.ts): `apps/backend/src/modules/prompts/prompt.controller.ts`
- [Prompt Operations](https://github.com/binarystudioacademy/bsa-2026-promtomat/tree/main/apps/backend/src/modules/prompts): `apps/backend/src/modules/prompts`
- [Embedding Service](https://github.com/binarystudioacademy/bsa-2026-promtomat/blob/main/apps/backend/src/modules/prompt-embeddings/prompt-embedding.service.ts): `apps/backend/src/modules/prompt-embeddings/prompt-embedding.service.ts`
- [Vector Queries](https://github.com/binarystudioacademy/bsa-2026-promtomat/blob/main/apps/backend/src/modules/prompt-embeddings/prompt-embedding.repository.ts): `apps/backend/src/modules/prompt-embeddings/prompt-embedding.repository.ts`
- [Prompt Composition](https://github.com/binarystudioacademy/bsa-2026-promtomat/blob/main/apps/backend/src/modules/composed-prompts/composed-prompt.service.ts): `apps/backend/src/modules/composed-prompts/composed-prompt.service.ts`

### Workspace Data

- [Workspace Management](https://github.com/binarystudioacademy/bsa-2026-promtomat/blob/main/apps/backend/src/modules/workspaces/workspace.controller.ts): `apps/backend/src/modules/workspaces/workspace.controller.ts`
- [Contributors](https://github.com/binarystudioacademy/bsa-2026-promtomat/blob/main/apps/backend/src/modules/contributors/contributor.controller.ts): `apps/backend/src/modules/contributors/contributor.controller.ts`
- [Labels](https://github.com/binarystudioacademy/bsa-2026-promtomat/tree/main/apps/backend/src/modules/labels): `apps/backend/src/modules/labels`
- [Repository Bindings](https://github.com/binarystudioacademy/bsa-2026-promtomat/blob/main/apps/backend/src/modules/repository-bindings/repository-binding.controller.ts): `apps/backend/src/modules/repository-bindings/repository-binding.controller.ts`

### Platform Services

- [Authentication](https://github.com/binarystudioacademy/bsa-2026-promtomat/tree/main/apps/backend/src/modules/auth): `apps/backend/src/modules/auth`
- [API Tokens](https://github.com/binarystudioacademy/bsa-2026-promtomat/tree/main/apps/backend/src/modules/api-tokens): `apps/backend/src/modules/api-tokens`
- [Embedding Model](https://github.com/binarystudioacademy/bsa-2026-promtomat/blob/main/apps/backend/src/libs/modules/embedding/embedding.ts): `apps/backend/src/libs/modules/embedding/embedding.ts`
- [Text Generation](https://github.com/binarystudioacademy/bsa-2026-promtomat/blob/main/apps/backend/src/libs/modules/generator/generator.ts): `apps/backend/src/libs/modules/generator/generator.ts`

### Agent Access

- [Local MCP Server](https://github.com/binarystudioacademy/bsa-2026-promtomat/tree/main/apps/mcp): `apps/mcp`

### Other components

- **Users**
- **Coding Agents**
- **Frontend**
- **Bedrock**
- **PostgreSQL pgvector**

## Connections

- Users → Frontend: uses
- Frontend → Backend API: calls API
- Coding Agents → Local MCP Server: starts locally
- Local MCP Server → Backend API: calls API
- Backend API → Authentication: authenticates
- Backend API → API Tokens: validates tokens
- Backend API → Prompt API: dispatches routes
- Prompt API → Prompt Operations: delegates
- Prompt Operations → Embedding Service: searches semantically
- Embedding Service → Embedding Model: embeds text
- Embedding Service → Vector Queries: queries and stores
- Vector Queries → PostgreSQL pgvector: reads and writes
- Backend API → Prompt Composition: dispatches routes
- Prompt Composition → Text Generation: generates output
- Text Generation → Bedrock: invokes model
- Backend API → Workspace Management: dispatches routes
- Backend API → Contributors: dispatches routes
- Backend API → Labels: dispatches routes
- Backend API → Repository Bindings: dispatches routes
- Backend API → Prompt Analytics: dispatches routes
- Workspace Management → PostgreSQL pgvector: persists workspace data
- Contributors → PostgreSQL pgvector: persists membership
- Labels → PostgreSQL pgvector: persists labels
- Repository Bindings → PostgreSQL pgvector: persists bindings
- Prompt Analytics → PostgreSQL pgvector: queries metrics