# sakthivelvelmurugan/comment-box architecture

> Architecture diagram of the GitHub repository sakthivelvelmurugan/comment-box, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sakthivelvelmurugan/comment-box
- Repository: https://github.com/sakthivelvelmurugan/comment-box

## Overview

#### Purpose and entry points
CommentBox is a stateless Java 17/Spring Boot REST service that turns submitted source code into commented code through OpenRouter-hosted LLMs. The process starts at `src/main/java/com/commentbox/api/CommentboxApiApplication.java`; its public API is `POST /api/v1/comments/generate` in `src/main/java/com/commentbox/api/controller/CommentController.java`. It also serves a small static browser UI from `src/main/resources/static/index.html`.

#### HTTP/API boundary
`CommentController` accepts a typed generation payload—language, comment style, density, code, and optional BYOK key—using `src/main/java/com/commentbox/api/model/CommentRequest.java`. It returns the generated code plus request/provider metadata via `src/main/java/com/commentbox/api/model/CommentResponse.java`. CORS policy is centralized in `src/main/java/com/commentbox/api/config/CorsConfig.java`.

#### Generation orchestration
`src/main/java/com/commentbox/api/service/CommentService.java` is the core application stage: it coordinates request handling, key selection, prompt creation, invocation of the model provider, and response shaping. The service is stateless: there is no persistence layer or database in the repository. Any usage/remaining-generation information is therefore request/service-level rather than durable application state.

#### Prompt and provider boundary
`src/main/java/com/commentbox/api/util/PromptBuilder.java` converts language, style, density, and raw code into the LLM instruction payload. `src/main/java/com/commentbox/api/config/OpenRouterConfig.java` configures Spring WebFlux `WebClient`, separating outbound OpenRouter HTTP integration from controller logic. The configured provider is OpenRouter, with GPT-4o-mini described as the target model; credentials come from a request `apiKey` when supplied, otherwise backend environment configuration.

#### Security and sensitive inputs
`src/main/java/com/commentbox/api/service/EncryptionService.java` is the dedicated boundary for handling sensitive material, notably user-supplied API-key flow. The API supports BYOK and a server-side `OPENROUTER_API_KEY`; callers should not expect keys to be persisted, consistent with the stateless design.

#### Validation and failure handling
Input-size and request/provider failures flow through application-specific exceptions in `src/main/java/com/commentbox/api/util/LimitExceededException.java` and `src/main/java/com/commentbox/api/util/ApiException.java`. `src/main/java/com/commentbox/api/config/GlobalExceptionHandler.java` maps these failures into the API error contract represented by `src/main/java/com/commentbox/api/util/ErrorResponse.java`, keeping error translation outside core generation logic.

#### Runtime and deployment
Spring Boot runs on port 8085 and exposes health through Actuator. Base and production runtime properties are in `src/main/resources/application.properties` and `src/main/resources/application-prod.properties`. Maven builds the service (`pom.xml`); `Dockerfile` packages it as a lean Alpine-based container. Deployment metadata targets Railway (`railway.toml`) and Vercel (`vercel.json`), with production behavior selected through `SPRING_PROFILES_ACTIVE=prod`.

Main entry points: [`src/main/java/com/commentbox/api/service/CommentService.java`](https://github.com/sakthivelvelmurugan/comment-box/blob/main/src/main/java/com/commentbox/api/service/CommentService.java) (Comment service), [`src/main/java/com/commentbox/api/CommentboxApiApplication.java`](https://github.com/sakthivelvelmurugan/comment-box/blob/main/src/main/java/com/commentbox/api/CommentboxApiApplication.java) (Spring Boot application), [`src/main/java/com/commentbox/api/controller/CommentController.java`](https://github.com/sakthivelvelmurugan/comment-box/blob/main/src/main/java/com/commentbox/api/controller/CommentController.java) (Comment endpoint), [`src/main/java/com/commentbox/api/config/GlobalExceptionHandler.java`](https://github.com/sakthivelvelmurugan/comment-box/blob/main/src/main/java/com/commentbox/api/config/GlobalExceptionHandler.java) (Error translation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_browser_ui["Static browser UI<br/>static UI<br/>[index.html]"]
  node_controller["Comment endpoint<br/>REST controller"]
  node_request["Generation request<br/>API request model"]
  node_response["Generation response<br/>API response model"]
  node_cors["CORS policy<br/>web configuration<br/>[CorsConfig.java]"]
  node_api_exception["Provider failures<br/>application exception<br/>[ApiException.java]"]
  node_limit_exception["Input limit failures<br/>application exception"]
  node_exception_handler["Error translation<br/>global exception handler"]
  node_error_response["API error response<br/>error contract<br/>[ErrorResponse.java]"]
end

subgraph group_generation["Generation pipeline"]
  node_comment_service["Comment service<br/>generation orchestrator"]
  node_encryption["Sensitive key handling<br/>security service"]
  node_prompt_builder["Prompt builder<br/>prompt construction<br/>[PromptBuilder.java]"]
end

subgraph group_provider["Provider integration"]
  node_webclient_config["OpenRouter WebClient<br/>outbound HTTP configuration"]
  node_openrouter{{"OpenRouter / GPT-4o-mini<br/>LLM provider"}}
end

subgraph group_runtime["Runtime &amp; deployment"]
  node_application{{"Spring Boot application<br/>application entry point"}}
  node_runtime_config["Production runtime config<br/>Spring properties"]
  node_actuator["Actuator health<br/>health endpoint"]
  node_container["Container build<br/>Docker image"]
  node_railway["Railway deployment<br/>deployment target<br/>[railway.toml]"]
  node_vercel["Vercel deployment<br/>deployment target<br/>[vercel.json]"]
end

node_browser_ui -->|"submits generation request"| node_controller
node_application -->|"starts"| node_controller
node_application -->|"loads"| node_cors
node_application -.->|"uses production profile"| node_runtime_config
node_application -->|"exposes health"| node_actuator
node_controller -->|"binds"| node_request
node_controller -->|"delegates"| node_comment_service
node_controller -->|"returns"| node_response
node_comment_service -->|"handles BYOK key"| node_encryption
node_comment_service -->|"builds instruction"| node_prompt_builder
node_comment_service -->|"invokes through"| node_webclient_config
node_webclient_config -->|"outbound model request"| node_openrouter
node_comment_service -.->|"raises provider failures"| node_api_exception
node_comment_service -.->|"raises size failures"| node_limit_exception
node_api_exception -->|"handled by"| node_exception_handler
node_limit_exception -->|"handled by"| node_exception_handler
node_exception_handler -->|"maps to"| node_error_response
node_container -->|"packages"| node_application
node_railway -->|"deploys"| node_container
node_vercel -->|"deploys"| node_container

click node_browser_ui "https://github.com/sakthivelvelmurugan/comment-box/blob/main/src/main/resources/static/index.html"
click node_application "https://github.com/sakthivelvelmurugan/comment-box/blob/main/src/main/java/com/commentbox/api/CommentboxApiApplication.java"
click node_controller "https://github.com/sakthivelvelmurugan/comment-box/blob/main/src/main/java/com/commentbox/api/controller/CommentController.java"
click node_request "https://github.com/sakthivelvelmurugan/comment-box/blob/main/src/main/java/com/commentbox/api/model/CommentRequest.java"
click node_response "https://github.com/sakthivelvelmurugan/comment-box/blob/main/src/main/java/com/commentbox/api/model/CommentResponse.java"
click node_cors "https://github.com/sakthivelvelmurugan/comment-box/blob/main/src/main/java/com/commentbox/api/config/CorsConfig.java"
click node_comment_service "https://github.com/sakthivelvelmurugan/comment-box/blob/main/src/main/java/com/commentbox/api/service/CommentService.java"
click node_encryption "https://github.com/sakthivelvelmurugan/comment-box/blob/main/src/main/java/com/commentbox/api/service/EncryptionService.java"
click node_prompt_builder "https://github.com/sakthivelvelmurugan/comment-box/blob/main/src/main/java/com/commentbox/api/util/PromptBuilder.java"
click node_webclient_config "https://github.com/sakthivelvelmurugan/comment-box/blob/main/src/main/java/com/commentbox/api/config/OpenRouterConfig.java"
click node_api_exception "https://github.com/sakthivelvelmurugan/comment-box/blob/main/src/main/java/com/commentbox/api/util/ApiException.java"
click node_limit_exception "https://github.com/sakthivelvelmurugan/comment-box/blob/main/src/main/java/com/commentbox/api/util/LimitExceededException.java"
click node_exception_handler "https://github.com/sakthivelvelmurugan/comment-box/blob/main/src/main/java/com/commentbox/api/config/GlobalExceptionHandler.java"
click node_error_response "https://github.com/sakthivelvelmurugan/comment-box/blob/main/src/main/java/com/commentbox/api/util/ErrorResponse.java"
click node_runtime_config "https://github.com/sakthivelvelmurugan/comment-box/blob/main/src/main/resources/application-prod.properties"
click node_container "https://github.com/sakthivelvelmurugan/comment-box/blob/main/Dockerfile"
click node_railway "https://github.com/sakthivelvelmurugan/comment-box/blob/main/railway.toml"
click node_vercel "https://github.com/sakthivelvelmurugan/comment-box/blob/main/vercel.json"

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_browser_ui,node_controller,node_request,node_response,node_cors,node_api_exception,node_limit_exception,node_exception_handler,node_error_response toneBlue
class node_comment_service,node_encryption,node_prompt_builder toneAmber
class node_webclient_config,node_openrouter toneMint
class node_application,node_runtime_config,node_actuator,node_container,node_railway,node_vercel toneRose
```

## Components

### HTTP API

- [Static browser UI](https://github.com/sakthivelvelmurugan/comment-box/blob/main/src/main/resources/static/index.html): static UI · `src/main/resources/static/index.html`
- [Comment endpoint](https://github.com/sakthivelvelmurugan/comment-box/blob/main/src/main/java/com/commentbox/api/controller/CommentController.java): REST controller · POST /api/v1/comments/generate. · `src/main/java/com/commentbox/api/controller/CommentController.java`
- [Generation request](https://github.com/sakthivelvelmurugan/comment-box/blob/main/src/main/java/com/commentbox/api/model/CommentRequest.java): API request model · Carries code, language, style, density, and optional BYOK key. · `src/main/java/com/commentbox/api/model/CommentRequest.java`
- [Generation response](https://github.com/sakthivelvelmurugan/comment-box/blob/main/src/main/java/com/commentbox/api/model/CommentResponse.java): API response model · Returns commented code and provider metadata. · `src/main/java/com/commentbox/api/model/CommentResponse.java`
- [CORS policy](https://github.com/sakthivelvelmurugan/comment-box/blob/main/src/main/java/com/commentbox/api/config/CorsConfig.java): web configuration · `src/main/java/com/commentbox/api/config/CorsConfig.java`
- [Provider failures](https://github.com/sakthivelvelmurugan/comment-box/blob/main/src/main/java/com/commentbox/api/util/ApiException.java): application exception · `src/main/java/com/commentbox/api/util/ApiException.java`
- [Input limit failures](https://github.com/sakthivelvelmurugan/comment-box/blob/main/src/main/java/com/commentbox/api/util/LimitExceededException.java): application exception · `src/main/java/com/commentbox/api/util/LimitExceededException.java`
- [Error translation](https://github.com/sakthivelvelmurugan/comment-box/blob/main/src/main/java/com/commentbox/api/config/GlobalExceptionHandler.java): global exception handler · `src/main/java/com/commentbox/api/config/GlobalExceptionHandler.java`
- [API error response](https://github.com/sakthivelvelmurugan/comment-box/blob/main/src/main/java/com/commentbox/api/util/ErrorResponse.java): error contract · `src/main/java/com/commentbox/api/util/ErrorResponse.java`

### Generation pipeline

- [Comment service](https://github.com/sakthivelvelmurugan/comment-box/blob/main/src/main/java/com/commentbox/api/service/CommentService.java): generation orchestrator · Statelessly selects credentials, builds prompts, invokes the model, and shapes responses. · `src/main/java/com/commentbox/api/service/CommentService.java`
- [Sensitive key handling](https://github.com/sakthivelvelmurugan/comment-box/blob/main/src/main/java/com/commentbox/api/service/EncryptionService.java): security service · Dedicated boundary for user-supplied API keys. · `src/main/java/com/commentbox/api/service/EncryptionService.java`
- [Prompt builder](https://github.com/sakthivelvelmurugan/comment-box/blob/main/src/main/java/com/commentbox/api/util/PromptBuilder.java): prompt construction · `src/main/java/com/commentbox/api/util/PromptBuilder.java`

### Provider integration

- [OpenRouter WebClient](https://github.com/sakthivelvelmurugan/comment-box/blob/main/src/main/java/com/commentbox/api/config/OpenRouterConfig.java): outbound HTTP configuration · `src/main/java/com/commentbox/api/config/OpenRouterConfig.java`
- **OpenRouter / GPT-4o-mini**: LLM provider · External model endpoint.

### Runtime & deployment

- [Spring Boot application](https://github.com/sakthivelvelmurugan/comment-box/blob/main/src/main/java/com/commentbox/api/CommentboxApiApplication.java): application entry point · `src/main/java/com/commentbox/api/CommentboxApiApplication.java`
- [Production runtime config](https://github.com/sakthivelvelmurugan/comment-box/blob/main/src/main/resources/application-prod.properties): Spring properties · Port 8085; production profile is selected with SPRING_PROFILES_ACTIVE=prod. · `src/main/resources/application-prod.properties`
- **Actuator health**: health endpoint
- [Container build](https://github.com/sakthivelvelmurugan/comment-box/blob/main/Dockerfile): Docker image · Alpine-based service package. · `Dockerfile`
- [Railway deployment](https://github.com/sakthivelvelmurugan/comment-box/blob/main/railway.toml): deployment target · `railway.toml`
- [Vercel deployment](https://github.com/sakthivelvelmurugan/comment-box/blob/main/vercel.json): deployment target · `vercel.json`

## Connections

- Static browser UI → Comment endpoint: submits generation request
- Spring Boot application → Comment endpoint: starts
- Spring Boot application → CORS policy: loads
- Spring Boot application → Production runtime config: uses production profile
- Spring Boot application → Actuator health: exposes health
- Comment endpoint → Generation request: binds
- Comment endpoint → Comment service: delegates
- Comment endpoint → Generation response: returns
- Comment service → Sensitive key handling: handles BYOK key
- Comment service → Prompt builder: builds instruction
- Comment service → OpenRouter WebClient: invokes through
- OpenRouter WebClient → OpenRouter / GPT-4o-mini: outbound model request
- Comment service → Provider failures: raises provider failures
- Comment service → Input limit failures: raises size failures
- Provider failures → Error translation: handled by
- Input limit failures → Error translation: handled by
- Error translation → API error response: maps to
- Container build → Spring Boot application: packages
- Railway deployment → Container build: deploys
- Vercel deployment → Container build: deploys