# upayanmazumder/kodesphere architecture

> Architecture diagram of the GitHub repository upayanmazumder/kodesphere, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/upayanmazumder/kodesphere
- Repository: https://github.com/upayanmazumder/kodesphere

## Overview

##### Main Components
- Frontend (Web Application):
- Located in the “app” directory. It is built with Next.js (as seen from the Next configuration and _app.js, _document.js pages) and contains the UI components (e.g., login screens, dashboard, hero, GitHub login, etc.).
- This component serves the client-side experience where users can trigger deployments and manage their applications.
- Backend API:
- Found in the “api” directory. It includes controllers (authController, createUser, githubController), routes (analyze, auth, getAIresponse, github), and configuration files (passport.js).
- This API handles user requests such as deploying applications by processing Docker image specifications, subdomain details, environment variables, and deployment lifecycle events.
- Containerization and Deployment Components:
- Dockerfiles at the root, inside “k8s” and GitHub workflows indicate CI/CD pipelines.
- The “docker-compose.yml” and “k8s-config” directories contain Kubernetes deployment files (Deployment, Ingress, Service, and cluster issuer configurations) which are crucial for orchestrating deployments.
- Kubernetes Cluster & Ingress Controller:
- As described in the README, Kubernetes manages the orchestration of deployments. The ingress configurations (api-ingress.yaml in k8s-config) manage the incoming traffic based on subdomain patterns.
- External DNS mapping and port mapping are also part of this layer.
- CI/CD Pipeline:
- Several GitHub workflows (.github/workflows) handle Docker image build and deployment processes. They ensure that both the main application and the Kubernetes deployment images are updated (referencing “docker-image-k8s.yml” and “docker-image-main.yml”).
- Auxiliary Assets & Documentation:
- The assets directory (with presentation files and business model canvas) and the k8s configuration documentation provide insight into the business logic and production deployment aspects.

##### Relationships and Data Flow
- Users interact with the Frontend (hosted at ks.upayan.dev) which offers a dashboard and controls to deploy applications.
- The Frontend communicates with the Backend API (api.ks.upayan.dev) via HTTP/HTTPS calls.
- The API receives deployment requests that include details such as users’ Docker image references, subdomain choices, ports, and environment variables.
- The API then interacts with the Kubernetes cluster orchestrator (api.vitians.in) to trigger deployments using Kubernetes manifests defined in the “k8s-config” directory.
- The CI/CD pipeline (via GitHub workflows) automatically builds and pushes Docker images to GitHub Container Registry, updating both the main kodesphere image and the Kubernetes deployment image.
- Finally, the Ingress controller routes incoming requests from the user’s subdomain to the correct deployed application instance.

##### Architectural Patterns and Technologies
- Separation of Concerns / Layered Architecture: There is a clear separation between the Frontend (UI) and Backend API.
- Containerization: Docker is heavily used to package applications.
- Orchestration: Kubernetes is central to managing scalability and deployment, with precise ingress configuration for subdomain routing.
- CI/CD: GitHub workflows automate image building and deployments.
- Microservices Elements: While the project is monorepo, the separation into “app” and “api” and use of separate images hint at a microservices or at least decoupled service design.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Components
    User("User/Client"):::client
    Frontend("Frontend Web App (ks.upayan.dev)"):::frontend
    Backend("Backend API (api.ks.upayan.dev)"):::backend
    CICD("CI/CD Pipeline (GitHub Actions)"):::cicd
    Registry("Docker Registry (ghcr.io/upayanmazumder/kodesphere)"):::registry
    K8s("Kubernetes Cluster (api.vitians.in)"):::k8s
    GitRepo("GitHub Repository"):::repo
    Aux("Auxiliary Assets & Documentation"):::aux

    %% Deployment Components Subgraph
    subgraph "Containerization & Deployment Components"
        D1("Dockerfile (Root)"):::deploy
        D2("Dockerfile (k8s)"):::deploy
        DC("docker-compose.yml"):::deploy
        K8sConfig("K8s Config (Manifests)"):::deploy
    end

    %% Inside Kubernetes: Ingress and Deployment/Service
    subgraph "Kubernetes Internal"
        Ingress("Ingress Controller"):::ingress
        Deploy("Deployment/Service"):::k8s
    end

    %% Connections and Data Flow
    User -->|"HTTP/HTTPS"| Frontend
    Frontend -->|"APICalls"| Backend
    Backend -->|"Deploys"| K8s
    CICD -->|"Build&Push"| Registry
    CICD -->|"DeployUpdates"| K8s
    GitRepo -->|"CI/CDIntegration"| CICD
    Ingress -->|"RoutesTraffic"| Deploy

    %% Click Events
    click Frontend "https://github.com/upayanmazumder/kodesphere/tree/main/app/"
    click Backend "https://github.com/upayanmazumder/kodesphere/tree/main/api/"
    click D1 "https://github.com/upayanmazumder/kodesphere/tree/main/Dockerfile"
    click D2 "https://github.com/upayanmazumder/kodesphere/tree/main/k8s/Dockerfile"
    click DC "https://github.com/upayanmazumder/kodesphere/blob/main/docker-compose.yml"
    click K8sConfig "https://github.com/upayanmazumder/kodesphere/tree/main/k8s-config/"
    click CICD "https://github.com/upayanmazumder/kodesphere/tree/main/.github/workflows/"
    click Ingress "https://github.com/upayanmazumder/kodesphere/blob/main/k8s-config/api-ingress.yaml"
    click Aux "https://github.com/upayanmazumder/kodesphere/tree/main/assets/"

    %% Styles
    classDef client fill:#cce5ff,stroke:#0056b3,stroke-width:2px;
    classDef frontend fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef backend fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef cicd fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef registry fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef k8s fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef ingress fill:#fad7a0,stroke:#e67e22,stroke-width:2px;
    classDef deploy fill:#f5f5f5,stroke:#333,stroke-width:2px;
    classDef aux fill:#d6d8d9,stroke:#1b1e21,stroke-width:2px;
    classDef repo fill:#ffcccc,stroke:#ff0000,stroke-width:2px;
```
