# jrv-xvi/oci-chatbot architecture

> Architecture diagram of the GitHub repository jrv-xvi/oci-chatbot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jrv-xvi/oci-chatbot
- Repository: https://github.com/jrv-xvi/oci-chatbot

## Overview

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: [`forgetask/src/main/java/com/cloudforge/api/forgetask/controller`](https://github.com/jrv-xvi/oci-chatbot/tree/main/forgetask/src/main/java/com/cloudforge/api/forgetask/controller) (API Layer), [`infrastructure/kubernetes/templates`](https://github.com/jrv-xvi/oci-chatbot/tree/main/infrastructure/kubernetes/templates) (Kubernetes), [`forgetask-frontend/app`](https://github.com/jrv-xvi/oci-chatbot/tree/main/forgetask-frontend/app) (App Router), [`forgetask-frontend/app/components/kanban`](https://github.com/jrv-xvi/oci-chatbot/tree/main/forgetask-frontend/app/components/kanban) (Kanban UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Next.js frontend"]
  node_frontend_app["App Router<br/>Next.js UI shell"]
  node_frontend_kanban["Kanban UI<br/>workspace components"]
  node_frontend_kpis["KPI Widgets<br/>dashboard components"]
  node_frontend_services["API Services<br/>HTTP client layer"]
  node_frontend_state["Task State<br/>client store"]
  node_frontend_primitives["UI Primitives<br/>shared components"]
end

subgraph group_backend["Spring Boot backend"]
  node_backend_api["API Layer<br/>Spring controllers"]
  node_backend_auth["Auth Flow<br/>security service"]
  node_backend_invites["Invites<br/>onboarding service"]
  node_backend_task["Task Domain<br/>work management service"]
  node_backend_kpi["Analytics<br/>reporting service"]
  node_backend_models["Domain Model<br/>JPA entities"]
  node_backend_repos["Repositories<br/>data access"]
  node_backend_config["Config & Security<br/>boot config"]
  node_backend_bot_ai["Bot & AI<br/>integration services"]
end

subgraph group_infra["Deployment layer"]
  node_infra_terraform["Terraform<br/>OCI IaC"]
  node_infra_k8s["Kubernetes<br/>runtime manifests"]
  node_infra_scripts["Deploy Scripts<br/>release automation"]
end

subgraph group_tests["E2E tests"]
  node_tests_selenium["Selenium E2E<br/>browser tests"]
end

subgraph group_external["External systems"]
  node_external_db[("Oracle DB<br/>managed database")]
  node_external_telegram(("Telegram<br/>external integration"))
  node_external_llm(("LLM API<br/>external integration"))
end

node_frontend_app -->|"renders"| node_frontend_kanban
node_frontend_app -->|"renders"| node_frontend_kpis
node_frontend_app -->|"uses"| node_frontend_primitives
node_frontend_kanban -->|"calls"| node_frontend_services
node_frontend_kpis -->|"loads"| node_frontend_services
node_frontend_kanban -->|"syncs"| node_frontend_state
node_frontend_state -->|"websocket"| node_backend_api
node_frontend_services -->|"REST"| node_backend_api
node_backend_api -->|"delegates"| node_backend_auth
node_backend_api -->|"delegates"| node_backend_invites
node_backend_api -->|"delegates"| node_backend_task
node_backend_api -->|"delegates"| node_backend_kpi
node_backend_auth -->|"uses"| node_backend_config
node_backend_task -->|"persists"| node_backend_models
node_backend_task -->|"reads/writes"| node_backend_repos
node_backend_invites -->|"uses"| node_backend_models
node_backend_kpi -->|"queries"| node_backend_repos
node_backend_api -->|"integrates"| node_backend_bot_ai
node_backend_bot_ai -->|"connects"| node_external_telegram
node_backend_bot_ai -->|"calls"| node_external_llm
node_backend_repos -->|"stores"| node_external_db
node_infra_terraform -->|"provisions"| node_external_db
node_infra_terraform -->|"supports"| node_infra_k8s
node_infra_k8s -->|"deploys"| node_backend_api
node_infra_k8s -->|"deploys"| node_frontend_app
node_infra_k8s -->|"runs"| node_tests_selenium
node_infra_scripts -->|"drives"| node_infra_terraform
node_infra_scripts -->|"drives"| node_infra_k8s
node_tests_selenium -->|"tests"| node_frontend_app
node_tests_selenium -->|"tests"| node_backend_api

click node_frontend_app "https://github.com/jrv-xvi/oci-chatbot/tree/main/forgetask-frontend/app"
click node_frontend_kanban "https://github.com/jrv-xvi/oci-chatbot/tree/main/forgetask-frontend/app/components/kanban"
click node_frontend_kpis "https://github.com/jrv-xvi/oci-chatbot/tree/main/forgetask-frontend/app/components/kpis"
click node_frontend_services "https://github.com/jrv-xvi/oci-chatbot/tree/main/forgetask-frontend/app/services"
click node_frontend_state "https://github.com/jrv-xvi/oci-chatbot/tree/main/forgetask-frontend/app/store"
click node_frontend_primitives "https://github.com/jrv-xvi/oci-chatbot/tree/main/forgetask-frontend/app/components/ui"
click node_backend_api "https://github.com/jrv-xvi/oci-chatbot/tree/main/forgetask/src/main/java/com/cloudforge/api/forgetask/controller"
click node_backend_auth "https://github.com/jrv-xvi/oci-chatbot/tree/main/forgetask/src/main/java/com/cloudforge/api/forgetask/service/auth"
click node_backend_invites "https://github.com/jrv-xvi/oci-chatbot/tree/main/forgetask/src/main/java/com/cloudforge/api/forgetask/service/invite"
click node_backend_task "https://github.com/jrv-xvi/oci-chatbot/tree/main/forgetask/src/main/java/com/cloudforge/api/forgetask/service"
click node_backend_kpi "https://github.com/jrv-xvi/oci-chatbot/tree/main/forgetask/src/main/java/com/cloudforge/api/forgetask/service"
click node_backend_models "https://github.com/jrv-xvi/oci-chatbot/tree/main/forgetask/src/main/java/com/cloudforge/api/forgetask/model"
click node_backend_repos "https://github.com/jrv-xvi/oci-chatbot/tree/main/forgetask/src/main/java/com/cloudforge/api/forgetask/repository"
click node_backend_config "https://github.com/jrv-xvi/oci-chatbot/tree/main/forgetask/src/main/java/com/cloudforge/api/forgetask/config"
click node_backend_bot_ai "https://github.com/jrv-xvi/oci-chatbot/tree/main/forgetask/src/main/java/com/cloudforge/api/forgetask/util"
click node_external_db "https://github.com/jrv-xvi/oci-chatbot/tree/main/forgetask/wallet"
click node_infra_terraform "https://github.com/jrv-xvi/oci-chatbot/tree/main/infrastructure/terraform"
click node_infra_k8s "https://github.com/jrv-xvi/oci-chatbot/tree/main/infrastructure/kubernetes/templates"
click node_infra_scripts "https://github.com/jrv-xvi/oci-chatbot/tree/main/infrastructure/scripts/deploy"
click node_tests_selenium "https://github.com/jrv-xvi/oci-chatbot/tree/main/tests/selenium"

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_frontend_app,node_frontend_kanban,node_frontend_kpis,node_frontend_services,node_frontend_state,node_frontend_primitives toneBlue
class node_backend_api,node_backend_auth,node_backend_invites,node_backend_task,node_backend_kpi,node_backend_models,node_backend_repos,node_backend_config,node_backend_bot_ai toneAmber
class node_infra_terraform,node_infra_k8s,node_infra_scripts toneMint
class node_tests_selenium toneRose
class node_external_db,node_external_telegram,node_external_llm toneIndigo
```

## Components

### Next.js frontend

React/TypeScript client app and UI surfaces.

- [App Router](https://github.com/jrv-xvi/oci-chatbot/tree/main/forgetask-frontend/app): Next.js UI shell · Top-level pages, layout, and routed screens for login, signup, onboarding, KPIs, and the main app. · `forgetask-frontend/app`
- [Kanban UI](https://github.com/jrv-xvi/oci-chatbot/tree/main/forgetask-frontend/app/components/kanban): workspace components · Board, task cards, dialogs, and project header for the main task workflow. · `forgetask-frontend/app/components/kanban`
- [KPI Widgets](https://github.com/jrv-xvi/oci-chatbot/tree/main/forgetask-frontend/app/components/kpis): dashboard components · KPI cards and chart components used to render reporting and analytics. · `forgetask-frontend/app/components/kpis`
- [API Services](https://github.com/jrv-xvi/oci-chatbot/tree/main/forgetask-frontend/app/services): HTTP client layer · Centralized wrappers for auth, health, projects, sprints, tasks, metrics, reports, and KPIs. · `forgetask-frontend/app/services`
- [Task State](https://github.com/jrv-xvi/oci-chatbot/tree/main/forgetask-frontend/app/store): client store · Client-side Kanban state and websocket hook for live task updates. · `forgetask-frontend/app/store`
- [UI Primitives](https://github.com/jrv-xvi/oci-chatbot/tree/main/forgetask-frontend/app/components/ui): shared components · 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](https://github.com/jrv-xvi/oci-chatbot/tree/main/forgetask/src/main/java/com/cloudforge/api/forgetask/controller): Spring controllers · 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](https://github.com/jrv-xvi/oci-chatbot/tree/main/forgetask/src/main/java/com/cloudforge/api/forgetask/service/auth): security service · Login/signup and JWT authentication/filtering for frontend access. · `forgetask/src/main/java/com/cloudforge/api/forgetask/service/auth`
- [Invites](https://github.com/jrv-xvi/oci-chatbot/tree/main/forgetask/src/main/java/com/cloudforge/api/forgetask/service/invite): onboarding service · Invite validation and project onboarding support. · `forgetask/src/main/java/com/cloudforge/api/forgetask/service/invite`
- [Task Domain](https://github.com/jrv-xvi/oci-chatbot/tree/main/forgetask/src/main/java/com/cloudforge/api/forgetask/service): work management service · Task lifecycle, websocket event messages, and board synchronization logic. · `forgetask/src/main/java/com/cloudforge/api/forgetask/service`
- [Analytics](https://github.com/jrv-xvi/oci-chatbot/tree/main/forgetask/src/main/java/com/cloudforge/api/forgetask/service): reporting service · KPI, metrics, report generation, and PDF/report projection logic. · `forgetask/src/main/java/com/cloudforge/api/forgetask/service`
- [Domain Model](https://github.com/jrv-xvi/oci-chatbot/tree/main/forgetask/src/main/java/com/cloudforge/api/forgetask/model): JPA entities · Core persistence models such as project, invite, account, and role entities. · `forgetask/src/main/java/com/cloudforge/api/forgetask/model`
- [Repositories](https://github.com/jrv-xvi/oci-chatbot/tree/main/forgetask/src/main/java/com/cloudforge/api/forgetask/repository): data access · Repository abstractions for project, invite, account, and role persistence. · `forgetask/src/main/java/com/cloudforge/api/forgetask/repository`
- [Config & Security](https://github.com/jrv-xvi/oci-chatbot/tree/main/forgetask/src/main/java/com/cloudforge/api/forgetask/config): boot config · Application, web, websocket, security, JWT, and LLM/Telegram configuration. · `forgetask/src/main/java/com/cloudforge/api/forgetask/config`
- [Bot & AI](https://github.com/jrv-xvi/oci-chatbot/tree/main/forgetask/src/main/java/com/cloudforge/api/forgetask/util): integration services · 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](https://github.com/jrv-xvi/oci-chatbot/tree/main/infrastructure/terraform): OCI IaC · OCI resource provisioning for gateway, container engine, storage, and database-related infrastructure. · `infrastructure/terraform`
- [Kubernetes](https://github.com/jrv-xvi/oci-chatbot/tree/main/infrastructure/kubernetes/templates): runtime manifests · Deployments and jobs for backend, frontend, e2e execution, and Selenium grid. · `infrastructure/kubernetes/templates`
- [Deploy Scripts](https://github.com/jrv-xvi/oci-chatbot/tree/main/infrastructure/scripts/deploy): release automation · Shell and helper scripts for build, deploy, setup, and destroy flows. · `infrastructure/scripts/deploy`

### E2E tests

Browser automation and test helpers.

- [Selenium E2E](https://github.com/jrv-xvi/oci-chatbot/tree/main/tests/selenium): browser tests · Page objects, cleanup helpers, and scenarios covering task and sprint flows. · `tests/selenium`

### External systems

Oracle database and third-party integrations.

- [Oracle DB](https://github.com/jrv-xvi/oci-chatbot/tree/main/forgetask/wallet): managed database · Oracle-backed persistence boundary, likely deployed via OCI wallet/network configuration. · `forgetask/wallet`
- **Telegram**: external integration · Telegram bot surface for reports and task actions.
- **LLM API**: external integration · Chat completion service used for conversational assistant features.

## Connections

- 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.
