# adpadillar/oci-telegram-bot architecture

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

- Interactive diagram: https://gitdiagram.com/adpadillar/oci-telegram-bot
- Repository: https://github.com/adpadillar/oci-telegram-bot

## Overview

##### Project type and purpose
- This is a full-stack, cloud-native “MyTodoList” application sample:
– Frontend: React-TypeScript Single-Page Application (SPA)
– Backend: Java Spring Boot monolith exposing RESTful APIs
– Deployment: OCI (Oracle Cloud Infrastructure) via Terraform, Docker, Kubernetes (OKE), API Gateway
- Purpose: Demonstrate a task/sprint/user management system with optional Telegram Bot integration and to provision all infra on OCI.

##### File structure
- Top level
– .github/workflows: CI checks (formatting, tests)
– oci_devops.yml: OCI DevOps pipeline definition
– package.json / pnpm-lock: frontend tooling config
– terraform/: IaC modules for OCI (API Gateway, OKE, DB, storage, networking)
– utils/: helper scripts for setup, teardown, Terraform, OKE auth
- MtdrSpring/backend
– Dockerfile + build.sh/dev.sh/deploy.sh scripts for local/dev/prod workflows
– src/main/frontend: React/Vite application
– src/main/java/com/springboot/MyTodoList: Spring Boot code
· config: CORS, DB, OpenAPI, security filters
· controller: REST endpoints for auth, users, tasks, sprints, projects, Telegram Bot webhook
· service & repository: business logic and Spring Data JPA
· dto/model: data transfer objects and ORM models
· util: bot commands/messages
– src/main/resources: YAML properties (DB connection, Telegram, server port)
– src/test/java: unit/integration tests for controllers

##### Key insights from README
- Environment variables for Oracle DB wallet, credentials, Telegram Bot details, server port
- Dev startup with dev.sh launches both backend and frontend (via Maven + npm/pnpm) on port 8081
- Prerequisites: oci-cli, Python, Terraform, kubectl, Maven

##### Main components
A. End User (Browser)
B. React SPA (served statically or via Spring Boot’s embedded server)
C. API Gateway (OCI)
D. Kubernetes Cluster (OKE)
1. Spring Boot Pod(s) behind a Kubernetes Service
E. Oracle Autonomous Database (or any OCI DB)
F. CI/CD Pipeline (GitHub Actions + OCI DevOps)
G. Terraform (IaC orchestration)
H. Optional: Telegram Bot external service
I. OCI Object Storage / Container Registry (for Docker images and static assets)

##### Relationships and interactions
- Browser → HTTP (HTTPS) → API Gateway → Kubernetes Service → Spring Boot Controller
- Spring Boot → JDBC → Oracle DB
- Spring Boot → HTTP → Telegram Bot API (outgoing webhook or polling)
- GitHub → CI/CD → OCI DevOps / GitHub Actions → Terraform apply → OKE + DB + API Gateway → Docker images pushed to Container Registry
- Terraform + utils scripts handle provisioning/destroying of OCI resources

##### Architectural patterns and design principles
- 3-Tier architecture: Presentation (React), Application (Spring Boot), Data (Oracle DB)
- MVC-ish within the backend: Controllers → Services → Repositories
- Infrastructure as Code (Terraform) for cloud provisioning
- Containerization (Docker) + Orchestration (Kubernetes)
- JWT-based authentication filter in Spring Security
- Single Page Application pattern in React with API client abstraction
- Separation of concerns: frontend build vs. backend API vs. infra provisioning

##### Relevant technologies/frameworks/libraries
- Frontend: React, TypeScript, Vite, React Query, axios (client.ts), Vitest
- Backend: Spring Boot, Spring Data JPA, JWT, Maven, Oracle JDBC
- Deployment: Docker, Kubernetes (OKE), OCI API Gateway, Terraform, OCI CLI
- CI/CD: GitHub Actions, OCI DevOps (oci_devops.yml)
- Utilities: bash scripts, Python for key generation and cluster token caching

##### Final advice
- Be exhaustive: decompose the Spring Boot monolith into its sub-layers (controllers, services, repositories) if needed
- Don’t omit infrastructure: Terraform modules, scripts, and CI/CD are core to the cloud-native design
- Keep it modular: group related components into logical clusters (e.g., “Backend Cluster”)
- Validate completeness by tracing a user story end-to-end (login → fetch tasks → persist data)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User & UI Layer
    subgraph "User & UI" 
        direction TB
        User["End User (Browser)"]:::user
        React["React SPA"]:::frontend
        click React "https://github.com/adpadillar/oci-telegram-bot/tree/main/MtdrSpring/backend/src/main/frontend"
        User -->|HTTPS 443| React
    end

    %% OCI Cloud Application Layer
    subgraph "OCI Cloud"
        direction TB
        APIGW["API Gateway"]:::cloud
        OKE["OKE Kubernetes Service"]:::compute

        subgraph "Spring Boot Monolith (Pods)" 
            direction TB
            MC["MyTodoListApplication"]:::compute
            Controllers["Controllers Layer"]:::compute
            Services["Services Layer"]:::compute
            Repos["Repositories Layer"]:::compute
            DTOs["DTOs & Models"]:::compute
            Security["Security Config (JWT, CORS)"]:::compute
            BotUtil["Telegram Bot Util & Config"]:::compute

            MC --> Controllers
            Controllers --> Services
            Services --> Repos
            Repos --> DB
            MC --> BotUtil

            click MC "https://github.com/adpadillar/oci-telegram-bot/blob/main/MtdrSpring/backend/src/main/java/com/springboot/MyTodoList/MyTodoListApplication.java"
            click Controllers "https://github.com/adpadillar/oci-telegram-bot/tree/main/MtdrSpring/backend/src/main/java/com/springboot/MyTodoList/controller"
            click Services "https://github.com/adpadillar/oci-telegram-bot/tree/main/MtdrSpring/backend/src/main/java/com/springboot/MyTodoList/service"
            click Repos "https://github.com/adpadillar/oci-telegram-bot/tree/main/MtdrSpring/backend/src/main/java/com/springboot/MyTodoList/repository"
            click DTOs "https://github.com/adpadillar/oci-telegram-bot/tree/main/MtdrSpring/backend/src/main/java/com/springboot/MyTodoList/dto"
            click Security "https://github.com/adpadillar/oci-telegram-bot/tree/main/MtdrSpring/backend/src/main/java/com/springboot/MyTodoList/security"
            click BotUtil "https://github.com/adpadillar/oci-telegram-bot/blob/main/MtdrSpring/backend/src/main/java/com/springboot/MyTodoList/util/BotHelper.java"
        end

        DB["Oracle Autonomous DB"]:::cloud
        Storage["OCI Object Storage"]:::cloud
        Registry["OCI Container Registry"]:::cloud
        ExternalBot["Telegram Bot API"]:::external

        React -->|API Calls| APIGW
        APIGW -->|HTTPS| OKE
        OKE --> MC
        Services -->|JDBC 1521| DB
        MC -->|HTTP| ExternalBot
        Registry -.-> OKE
        Storage -.-> React
    end

    %% CI/CD and IaC Layer
    subgraph "CI/CD & IaC"
        direction TB
        GHactions["GitHub Actions"]:::ci
        OCIDev["OCI DevOps Pipeline"]:::ci
        Terraform["Terraform IaC"]:::iac
        CI_scripts["Utility Scripts"]:::ci

        GHactions --> OCIDev
        OCIDev --> Terraform
        Terraform --> APIGW
        Terraform --> OKE
        Terraform --> DB
        Terraform --> Storage
        Terraform --> Registry

        click Terraform "https://github.com/adpadillar/oci-telegram-bot/blob/main/MtdrSpring/terraform/apigateway.tf"
        click Terraform "https://github.com/adpadillar/oci-telegram-bot/blob/main/MtdrSpring/terraform/containerengine.tf"
        click Terraform "https://github.com/adpadillar/oci-telegram-bot/blob/main/MtdrSpring/terraform/database.tf"
        click Terraform "https://github.com/adpadillar/oci-telegram-bot/blob/main/MtdrSpring/terraform/object_storage.tf"
        click Terraform "https://github.com/adpadillar/oci-telegram-bot/blob/main/MtdrSpring/terraform/repositories.tf"
        click Terraform "https://github.com/adpadillar/oci-telegram-bot/blob/main/MtdrSpring/terraform/core.tf"
        click Terraform "https://github.com/adpadillar/oci-telegram-bot/blob/main/MtdrSpring/terraform/provider.tf"
        click Terraform "https://github.com/adpadillar/oci-telegram-bot/blob/main/MtdrSpring/terraform/main-var.tf"
        click Terraform "https://github.com/adpadillar/oci-telegram-bot/blob/main/MtdrSpring/terraform/outputs.tf"
        click GHactions "https://github.com/adpadillar/oci-telegram-bot/blob/main/.github/workflows/format.yml"
        click GHactions "https://github.com/adpadillar/oci-telegram-bot/blob/main/.github/workflows/tests.yml"
        click OCIDev "https://github.com/adpadillar/oci-telegram-bot/blob/main/oci_devops.yml"
        click CI_scripts "https://github.com/adpadillar/oci-telegram-bot/blob/main/MtdrSpring/utils/terraform.sh"
        click CI_scripts "https://github.com/adpadillar/oci-telegram-bot/blob/main/MtdrSpring/utils/oke-setup.sh"
        click CI_scripts "https://github.com/adpadillar/oci-telegram-bot/blob/main/MtdrSpring/utils/kube_token_cache.sh"
        click CI_scripts "https://github.com/adpadillar/oci-telegram-bot/blob/main/MtdrSpring/utils/db-setup.sh"
    end

    classDef frontend fill:#ffe066,stroke:#333,stroke-width:1px
    classDef cloud fill:#a7f3d0,stroke:#333,stroke-width:1px
    classDef compute fill:#bfdbfe,stroke:#333,stroke-width:1px
    classDef ci fill:#e5e7eb,stroke:#333,stroke-width:1px
    classDef iac fill:#d1d5db,stroke:#333,stroke-width:1px
    classDef user fill:#fef08a,stroke:#333,stroke-width:1px
    classDef external fill:#fbcfe8,stroke:#333,stroke-width:1px
```
