sakthivelvelmurugan/comment-box

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.