Skip to main content

🔍 POC Analysis

This document analyzes the CBT Buddy backend POC built on Constellation (Springular boilerplate). It identifies proven patterns and capabilities that should be ported back to Constellation as business-agnostic modules, following the Roadmap.

Overview​

Important Context:

  • Constellation = Springular (same codebase, the boilerplate)
  • CBT Buddy backend is a POC built on Constellation to validate AI capabilities
  • POC learnings will be ported back to Constellation according to roadmap priorities
  • Nothing in the POC is "done" — it's proof of concept work that needs to be properly integrated

Porting Sequence:

  • Phase 1A: Port minimal ChatModel infrastructure first (unblocks Phase 2)
  • Phase 2: Build Text Intelligence Service (productized feature)
  • Phase 1B: Port full RAG/embeddings later (when products need it)

Approach: Focus on proven enhancements from the POC that:

  • Simplify implementation of business features
  • Reduce technical debt
  • Provide reusable, business-agnostic capabilities
  • Can be ported according to roadmap priorities

Analysis Date: December 2025
Source: CBT Buddy backend POC (constellation/cbt-buddy/backend)
Target: Constellation (Springular boilerplate) enhancement per roadmap

Incremental Changes from Springular Boilerplate​

1. AI Foundation Package (common/ai/)​

Components:

  • LangChain4j integration (Ollama chat + embeddings)
  • RAG with query compression and chat memory
  • Document entity with topic-based deduplication
  • pgvector embedding store
  • AI service abstraction (AIService, AIAssistant)
  • OpenAPI code generation (DTOs from spec)
  • Prompt template manager (partially implemented)
  • Constants class for centralized defaults
  • MapStruct mappers for response conversion

Business-Agnostic: Generic AI capabilities, topic-based categorization, reusable patterns

2. Database Migrations​

Migrations:

  • V3: Entity schema synchronization
  • V4: Enable pgvector extension
  • V5: RAG schema (documents, chunks tables)
  • V6: LangChain4j schema alignment (renames columns: vector→embedding, id→embedding_id, content→text, adds metadata jsonb)

Note: V6 migration is critical for LangChain4j compatibility

3. Docker Compose Enhancements​

Changes:

  • Ollama service with health checks
  • PostgreSQL image changed to pgvector/pgvector:pg15
  • Network configuration updates

4. Build.gradle Dependencies​

Added:

  • LangChain4j libraries (pgvector, ollama, embeddings) - version 1.3.0-beta9
  • OpenAPI generator plugin (code generation from spec)
  • Actuator configured for health checks

5. Application.yml Configuration​

Added:

  • Ollama configuration (models, timeout, temperature)
  • RAG configuration (embedding dimensions, chunk size, overlap, memory)
  • Actuator health check endpoints
  • Multiple Spring profiles (test, local, ai-test, ddl-generate)

6. Additional Components​

Constants Class (AiConstants.java): Centralized defaults (768 dimensions, model names, timeouts). Single source of truth.

MapStruct Mappers: EnhancedChatMapper and QuestionGenerationMapper convert LangChain4j Result<String> to response DTOs.

Prompt Template System: PromptTemplateManager exists but partially implemented. System prompts stored as .md files in resources/prompts/ (manager expects .json).

OpenAPI Code Generation: Gradle plugin generates DTOs from ai-service-openapi.yml to build/generated-sources/openapi. Controller implements generated interfaces.

JacksonConfiguration Enhancement: Adds JavaTimeModule registration for Java 8 date/time types (dec2025 missing this).

Test Infrastructure: Basic test files (AIServiceTest, AIControllerTest) showing mocking patterns.

Classification Summary​

All identified components are business-agnostic (generic AI infrastructure, reusable patterns, development tooling).

High Priority: AI foundation, pgvector/Ollama setup, RAG implementation, database migrations (V4-V6), constants class, JacksonConfiguration enhancement.

Medium Priority: Actuator/health checks, OpenAPI generation, MapStruct mappers, multiple Spring profiles.

Low Priority: Prompt template system (needs completion), DDL generation profile, test infrastructure.

Porting Priority (By Phase)​

Phase 1A Priority (Minimal Infrastructure):

  • AIConfiguration.java (ChatModel bean only)
  • AiConstants.java
  • Application.yml (Ollama config)
  • Docker Compose (Ollama service)
  • LangChain4j basic wiring

Phase 1B Priority (Full RAG - Port Later):

  • pgvector setup & migrations (V4-V6)
  • Document/Chunk entities
  • EmbeddingModel bean
  • EmbeddingStore implementation
  • RAG pipeline services

Phase 2 Priority (Text Intelligence Service):

  • TextIntelligenceService interface + implementation
  • Text generation (productized, extends Phase 1A)
  • Text rewriting (new capability)
  • Additional primitives (summarization, translation, etc.)

What's Missing in dec2025/springular​

Missing: Entire common/ai/ package, pgvector setup and migrations (V3-V6), Ollama service in Docker Compose, LangChain4j dependencies, AI configuration in application.yml, Actuator health checks, OpenAPI generator plugin, constants class pattern, JacksonConfiguration JavaTimeModule, MapStruct mappers for AI, prompt template system.

Implementation Plan​

Phase 1 - Infrastructure: Add Ollama to docker-compose.yml, switch to pgvector image, add LangChain4j dependencies, configure Actuator, enhance JacksonConfiguration with JavaTimeModule.

Phase 2 - Database: Add migrations V3 (schema sync), V4 (pgvector extension), V5 (RAG schema), V6 (LangChain4j column alignment - critical).

Phase 3 - AI Foundation: Port common/ai/ package structure, configuration classes, constants class, service interfaces, entity/repository, document management.

Phase 4 - Integration: Configure application.yml for AI, add OpenAPI generation (optional but recommended), add MapStruct mappers, test end-to-end flow.

Design Principles​

Topic-Based Categorization: Document entity uses topic field - works for any domain (cbt, legal, finance, etc.).

Generic Interfaces: AIService is domain-agnostic, no business-specific logic in service layer.

Configurable: All AI behavior via application.yml - models, timeouts, chunk sizes. No hardcoded logic.

Reusable Patterns: RAG for document search, embeddings for similarity search, chat memory for conversations.

Key Files to Port​

High Priority: AIConfiguration.java, AiConstants.java, AIService.java, AIServiceImpl.java, Document.java, DocumentRepository.java, JacksonConfiguration.java (with JavaTimeModule).

Medium Priority: AIController.java, MapStruct mapper interfaces, OpenAPI spec and generator setup.

Low Priority: PromptTemplateManager (needs completion), DDL generation profile, additional Spring profiles.

Implementation Dependencies​

Migrations must be applied in order: V3 → V4 → V5 → V6. V6 is critical - renames columns for LangChain4j compatibility. OpenAPI generation is optional but recommended for professional API documentation. Prompt template system exists but needs completion (.md files vs .json expectation).

Version Notes: Constellation uses LangChain4j 1.3.0-beta9 (beta). Consider stable versions if available. Default models: llama2:7b and nomic-embed-text (768 dimensions).

Springular → Constellation Feature Gap Map​

This shows exactly what Constellation needs to add, step by step, without overbuilding. Porting happens according to roadmap priorities.

🧱 What Springular Already Gives You​

(Strong base)

  • Auth
  • Billing (subscriptions)
  • User management
  • API structure
  • Frontend scaffold
  • CI/CD
  • Email
  • Docs

👉 This is perfect SaaS plumbing.

🚀 What Constellation Must Add (in Order)​

🔹 GAP 1 — AI Text Core (FIRST ADDITION)​

Enables: AI text product

Needed capabilities:

  • Prompt templates
  • Model abstraction (local/cloud)
  • Token & cost tracking
  • Text input/output UI

Why first:

  • Enables first product
  • Becomes dependency for everything else

POC Status: Text Intelligence patterns validated in CBT Buddy POC. See Text Intelligence Solution Architecture for system design. Implementation guides will be created for step-by-step instructions.

🔹 GAP 2 — AI Usage & Limits​

Enables: Paid tiers

Needed:

  • Per-user quotas
  • Request limits
  • Usage metrics
  • Soft/hard caps

Why:

  • Without this, AI SaaS bleeds money

🔹 GAP 3 — Knowledge Storage (Semantic Layer)​

Enables: Chat, search, personalization

Needed:

  • Document ingestion
  • Embeddings
  • Similarity search

POC Status: ✅ Validated in CBT Buddy POC (RAG with pgvector working)

🔹 GAP 4 — Conversational Runtime​

Enables: AI assistants

Needed:

  • Chat state
  • Memory
  • System prompts
  • Context injection

POC Status: Partially validated in CBT Buddy POC (chat memory patterns)

🔹 GAP 5 — Background Jobs​

Enables: Automation products

Needed:

  • Schedulers
  • Queues
  • Retries
  • Event triggers

Next Steps​

  1. Prioritize features to port according to roadmap
  2. Port infrastructure (Phase 1) - Docker, dependencies, configuration
  3. Port database migrations (Phase 2) - Execute in order V3→V4→V5→V6
  4. Port AI foundation (Phase 3) - Core package structure and services
  5. Integration and testing (Phase 4) - End-to-end validation

Post-POC Enhancement Ideas​

💡 Business Patterns Analysis: See Business Patterns for detailed analysis of successful business models and infrastructure needs.

💡 Roadmap: Porting POC learnings and future enhancements follow the Roadmap.

After successfully porting POC improvements, consider these pragmatic next steps based on existing infrastructure and common SaaS needs. These are future considerations, not immediate priorities:

🔥 High Value - Extend Existing Features​

User Management UI - Add admin interface to existing UserService (list, search, edit, role management). Critical for customer support and operations.

Dashboard Analytics - Replace placeholder with real metrics using existing Stripe integration (MRR, ARR, user growth, payment success rates). Essential for SaaS business tracking.

Settings/Preferences API - Add user settings entity and endpoints. Common need across all SaaS, enables user control and retention.

Background Job Processing - Add Spring @Async and @Scheduled to existing EmailService for async email queues and scheduled tasks. Improves UX and reduces request blocking.

External API Integration Framework - Generic OAuth flow handler, API key storage with encryption, HTTP client abstraction. Enables: Marketing analytics (Cometly), revenue tracking (TrustMRR), social media management (Followr.ai).

OAuth/API Key Management - Entity to store external service connections, encryption at rest, connection health checks. Enables: Multi-platform tools, aggregation platforms, integration businesses.

⚡ Medium Value - Common SaaS Infrastructure​

File Management - Upload/download service with storage abstraction (local/S3). Generic pattern for avatars, documents, attachments.

Notifications System - In-app notification entity and endpoints extending email service. Generic infrastructure for engagement and retention.

Audit Logging - Generic audit log entity (entity_type, entity_id, action, user_id, timestamp). Enables compliance, debugging, security tracking.

API Keys - Alternative authentication for programmatic access. Enables integrations, automation, webhooks foundation.

Scheduling System - Job scheduling entity with cron-like support, one-time and recurring jobs. Enables: Social media automation (Followr.ai), scheduled content, periodic aggregations.

Template Management - Generic template entity with variable substitution and versioning. Enables: Resume builders (Rezi), email templates, content generation tools (Editee).

Webhook Receivers - Generic webhook endpoint handler with signature verification and event routing. Enables: Real-time sync, event-driven automation, multi-platform integrations.

Data Aggregation Patterns - External data source entity, normalization layer, conflict resolution. Enables: Multi-source dashboards, unified views, aggregation platforms.

💡 Lower Priority - Quality of Life​

Webhooks (Outgoing) - Generic webhook delivery service. Builds on API keys infrastructure.

Data Export/Import - Generic CSV/JSON export/import for data portability. GDPR-ready, works for any entity.

Full-Text Search - PostgreSQL native search with GIN indexes. Generic pattern for searchable content.

Implementation Priority​

Focus first on extending existing infrastructure (user management UI, dashboard analytics, settings API, background jobs) for immediate business value with minimal new infrastructure. File management and notifications require new services but are common SaaS needs. Audit logging and API keys enable future integrations and compliance.

All features are business-agnostic, reusable patterns. Each should simplify business feature implementation or reduce technical debt.

Pragmatic Enhancement Principles​

When considering new boilerplate enhancements (beyond Constellation porting):

Add if it: Simplifies business feature implementation, reduces technical debt, provides reusable business-agnostic capabilities, proven useful in Constellation or other projects.

Don't add if it: Purely theoretical, adds complexity without clear benefit, too business-specific, requires significant maintenance overhead.

Focus: Build on proven Constellation improvements, then evaluate each new enhancement against these principles.

References​