How jrv-xvi/oci-chatbot works
1. This is a two-tier product with a clear split between a Next.js frontend and a Spring Boot backend, plus a separate infrastructure/deployment layer. The frontend lives in forgetask-frontend/; the backend API and domain logic live in forgetask/; deployment assets live under infrastructure/, with end-to-end tests under tests/ and infrastructure/shell/.
2. The frontend is a React/TypeScript app using the Next.js App Router. Its main user-facing surfaces are authentication (/login, /signup), onboarding (/onboarding), KPI dashboards (/kpis), and the main Kanban/task workspace (app/components/kanban/*). The app is composed from small UI primitives, chart/KPI widgets, and page-level containers.
3. Frontend data access is centralized in app/services/*, which wraps backend HTTP calls for auth, health, projects, sprints, tasks, metrics, reports, and KPIs. app/hooks/useTaskWebSocket.ts adds a realtime channel for task events, and app/store/taskStore.ts holds client-side task state for the Kanban experience.
4. The backend is a Java 17/Spring Boot service (com.cloudforge.api.forgetask) exposing REST controllers for auth, invites, projects, sprints, tasks, KPIs, metrics, reports, health, and Telegram bot operations. It also exposes a WebSocket controller for live task updates. This is the primary integration boundary for the frontend and for automation/integration features.
5. The backend is organized in typical layers: controllers, service classes, repositories, JPA models, DTOs, and security/configuration. Core persistence entities include Project, ProjectInvite, UserAccount, and role-related models; repositories abstract database access; DTOs carry API payloads and reporting/KPI projections.
6. Authentication and onboarding are first-class flows. AuthController and service/auth/AuthService handle login/signup, while JWT support is implemented through security/JwtUtil and security/JwtAuthFilter. Invite-based access is modeled separately with InviteController and service/invite/InviteService, which suggests project onboarding is tied to invitation validation and account creation.
7. The Kanban/task subsystem is both REST-driven and realtime. Task lifecycle changes are represented by dedicated message DTOs (TaskCreateMessage, TaskUpdateMessage, TaskDeleteMessage, TaskEventMessage) and are pushed over WebSocket so the frontend board can update live. This subsystem is the main operational path of the app: create/edit/delete tasks, move statuses, and synchronize board state across clients.
8. Reporting and analytics are a separate backend concern from task CRUD. KPIService, MetricsController, ReportController, and several KPI DTOs compute summaries such as total tasks, hours, average hours per developer, and sprint/user performance. The frontend renders these through chart and KPI components rather than computing them locally.
9. There are two external integration surfaces beyond the main UI: Telegram and LLM-assisted features. Telegram-specific config, controller, utilities, and report services indicate the backend can send or orchestrate reports and task actions via a bot. LLMConfig, LLMService, and related chat completion DTOs show an AI assistant integration path, likely for conversational task creation or analysis.
10. Persistence appears to target an Oracle database in OCI. The presence of an Oracle wallet directory, JDBC/network config files, and OCI deployment docs/scripts suggests the backend is designed to run against managed Oracle infrastructure rather than a local embedded database. That makes the database boundary an important deployment dependency.
11. The infrastructure layer is substantial and infrastructure-as-code oriented. infrastructure/terraform/* provisions OCI resources such as API gateway, container engine, object storage, and database-related components. infrastructure/kubernetes/templates/* defines runtime manifests for the backend, frontend, e2e job, and Selenium grid, indicating the system is deployed as multiple containers into Kubernetes.
12. Build and release are orchestrated with Docker and shell scripts. There are Dockerfiles for both app layers, compose files for development, and CI/deploy scripts under infrastructure/scripts/deploy. build_spec.yaml and the OCI deployment docs imply the project supports automated build/deploy pipelines in addition to local development.
13. Testing is split between backend unit tests and browser-level E2E tests. The backend has a standard Spring test scaffold, while tests/selenium/ contains page objects, API cleanup helpers, and scenarios for task creation/edit/delete and sprint creation. This tells you that UI behavior is validated end-to-end against the deployed frontend/backed stack, not just with component tests.
14. For an architecture diagram, the key boxes are: browser/client UI, Spring Boot API, realtime WebSocket channel, Oracle-backed persistence, Telegram/LLM external services, and the OCI/Kubernetes deployment platform. The most important arrows are: frontend → REST API, frontend ← WebSocket events, backend ↔ database, backend ↔ Telegram/LLM, and CI/CD → container/image/deployment infrastructure.
Main entry points: controller API Layer · templates Kubernetes · app App Router · kanban Kanban UI
Components 22
Next.js frontend
React/TypeScript client app and UI surfaces.
- App Router · Top-level pages, layout, and routed screens for login, signup, onboarding, KPIs, and the main app.
forgetask-frontend/app - Kanban UI · Board, task cards, dialogs, and project header for the main task workflow.
forgetask-frontend/app/components/kanban - KPI Widgets · KPI cards and chart components used to render reporting and analytics.
forgetask-frontend/app/components/kpis - API Services · Centralized wrappers for auth, health, projects, sprints, tasks, metrics, reports, and KPIs.
forgetask-frontend/app/services - Task State · Client-side Kanban state and websocket hook for live task updates.
forgetask-frontend/app/store - UI Primitives · Reusable buttons, dialogs, inputs, charts, and KPI building blocks.
forgetask-frontend/app/components/ui
Spring Boot backend
REST, realtime, domain, and persistence layers.
- API Layer · REST controllers for auth, invites, projects, sprints, tasks, KPIs, metrics, reports, health, and Telegram plus websocket task updates.
forgetask/src/main/java/com/cloudforge/api/forgetask/controller - Auth Flow · Login/signup and JWT authentication/filtering for frontend access.
forgetask/src/main/java/com/cloudforge/api/forgetask/service/auth - Invites · Invite validation and project onboarding support.
forgetask/src/main/java/com/cloudforge/api/forgetask/service/invite - Task Domain · Task lifecycle, websocket event messages, and board synchronization logic.
forgetask/src/main/java/com/cloudforge/api/forgetask/service - Analytics · KPI, metrics, report generation, and PDF/report projection logic.
forgetask/src/main/java/com/cloudforge/api/forgetask/service - Domain Model · Core persistence models such as project, invite, account, and role entities.
forgetask/src/main/java/com/cloudforge/api/forgetask/model - Repositories · Repository abstractions for project, invite, account, and role persistence.
forgetask/src/main/java/com/cloudforge/api/forgetask/repository - Config & Security · Application, web, websocket, security, JWT, and LLM/Telegram configuration.
forgetask/src/main/java/com/cloudforge/api/forgetask/config - Bot & AI · Telegram bot orchestration and LLM-assisted conversational task/report features.
forgetask/src/main/java/com/cloudforge/api/forgetask/util
Deployment layer
Terraform, Kubernetes, Docker, and shell automation.
- Terraform · OCI resource provisioning for gateway, container engine, storage, and database-related infrastructure.
infrastructure/terraform - Kubernetes · Deployments and jobs for backend, frontend, e2e execution, and Selenium grid.
infrastructure/kubernetes/templates - Deploy Scripts · Shell and helper scripts for build, deploy, setup, and destroy flows.
infrastructure/scripts/deploy
E2E tests
Browser automation and test helpers.
- Selenium E2E · Page objects, cleanup helpers, and scenarios covering task and sprint flows.
tests/selenium
External systems
Oracle database and third-party integrations.
- Oracle DB · Oracle-backed persistence boundary, likely deployed via OCI wallet/network configuration.
forgetask/wallet - Telegram · Telegram bot surface for reports and task actions.
- LLM API · Chat completion service used for conversational assistant features.
Connections 30
- App Router → Kanban UI: renders · App Router composes the main Kanban workspace and page surfaces.
- App Router → KPI Widgets: renders · KPI page surfaces analytics widgets and charts.
- App Router → UI Primitives: uses · Pages and feature components are built from shared UI primitives.
- Kanban UI → API Services: calls · Kanban interactions use centralized API services.
- KPI Widgets → API Services: loads · Dashboard widgets fetch KPI and report data through service wrappers.
- Kanban UI → Task State: syncs · Board interactions update local task state and receive realtime events.
- Task State → API Layer: websocket · Task updates flow through the live websocket channel.
- API Services → API Layer: REST · Frontend data access is centralized through backend HTTP endpoints.
- API Layer → Auth Flow: delegates · Auth endpoints use the authentication service and JWT plumbing.
- API Layer → Invites: delegates · Invite endpoints rely on invite validation and onboarding service logic.
- API Layer → Task Domain: delegates · Task controllers and websocket updates map into the task domain.
- API Layer → Analytics: delegates · KPI, metrics, and report endpoints use analytics services.
- Auth Flow → Config & Security: uses · Authentication depends on JWT filter/util and security configuration.
- Task Domain → Domain Model: persists · Task and project behavior is grounded in the JPA domain model.
- Task Domain → Repositories: reads/writes · Task workflows use repository abstractions for persistence.
- Invites → Domain Model: uses · Invite onboarding is backed by project invite and account models.
- Analytics → Repositories: queries · Analytics aggregates data through repositories and projections.
- API Layer → Bot & AI: integrates · Telegram and AI-assisted features are exposed through the backend boundary.
- Bot & AI → Telegram: connects · Telegram bot services communicate with the bot platform.
- Bot & AI → LLM API: calls · LLM configuration and service connect to chat completion APIs.
- Repositories → Oracle DB: stores · Repositories persist data to the Oracle database boundary.
- Terraform → Oracle DB: provisions · Terraform includes database-related OCI infrastructure.
- Terraform → Kubernetes: supports · Infrastructure provisioning feeds the Kubernetes runtime.
- Kubernetes → API Layer: deploys · Backend service is deployed as a Kubernetes workload.
- Kubernetes → App Router: deploys · Frontend is deployed as a Kubernetes workload.
- Kubernetes → Selenium E2E: runs · E2E tests are executed as a Kubernetes job alongside Selenium grid.
- Deploy Scripts → Terraform: drives · Shell automation wraps provisioning and release workflows.
- Deploy Scripts → Kubernetes: drives · Deployment scripts apply or manage Kubernetes resources.
- Selenium E2E → App Router: tests · Browser tests validate the frontend user flows.
- Selenium E2E → API Layer: tests · Scenarios exercise the live backend through the deployed stack.