# tonitienda/kadai architecture

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

- Interactive diagram: https://gitdiagram.com/tonitienda/kadai
- Repository: https://github.com/tonitienda/kadai

## Overview

##### Project Overview and Type
- The project is a multi-technology task management application designed as a playground to experiment with and learn a variety of technologies.
- It is a full-stack solution that implements different approaches for both frontend and backend. On the backend side, there are REST APIs implemented in Golang and JavaScript, while the frontend is represented by different implementations (Next.js and HTMX with Go). Additionally, testing frameworks (E2E with Cypress and system tests with BDD in Go) and various database options (in-memory and Mongo) are present.
- The README also shows a “wishlist” of desired techs, but the implemented ones (marked with ✔️) are the core parts.

##### Analyzing the File Structure
- Top-Level Directories: Notice several major sections:
- .docs directory holds documentation: architecture documents, design records (ADRs), use cases, and tasks.
- Backend directories: “backend-rest-go” (Golang) and “backend-rest-js” (JavaScript). They each contain their respective source code, tests, Dockerfiles, and build scripts.
- Frontend directories: “webapp-nextjs”, “webapp-htmx-go”, and “webapp-remix” (the last one being a work-in-progress as indicated by README notes).
- Testing: “bdd-go” for behavior-driven tests, and “e2e-cypress” for end-to-end tests.
- Compose files: Several docker-compose YAML files indicate different deployment and integration scenarios (backend-go, backend-js, dev, CI, DB options, etc.).
- The structure hints at a microservices or segregated backward/front-end approach while showing explicit boundaries between components.

To capture all essential architectural elements, include the following components and interactions:

a. Main Components:
- Web Applications (Frontend):
- Next.js-based application (located in webapp-nextjs)
- HTMX/Go based webapp (located in webapp-htmx-go)
- (Optionally, a Remix-based frontend as an experiment)
- Backends (API Services):
- REST API implemented in Go (backend-rest-go)
- REST API implemented in JavaScript/Node (backend-rest-js)
- Databases:
- In-Memory (found in backend-rest-go/pkg/tasks and similar)
- Mongo (integration in backend-rest-go/pkg/db/mongo.go)
- Testing Components:
- End-to-End testing using Cypress (e2e-cypress)
- System tests using Behavior-Driven Development in Go (bdd-go)
- Additional Infrastructure components (via docker-compose):
- Deployment orchestration using Docker and Compose files (multiple compose.*.yaml files)

b. Relationships and Interactions:
- The testing layers (both E2E and BDD system tests) will invoke or simulate interactions with the appropriate layers:
- E2E tests (Cypress) interact with the frontend applications.
- System tests (BDD Go) interact with backend API services.

c. Architectural Patterns and Design Principles:
- There is a clear separation of concerns between presentation, business logic, and data persistence.
- Microfrontend/microservice flavors are indicated by having multiple implementations of similar functionalities (e.g., nextjs vs. htmx-go).
- The modular and multi-technology approach shows that the project is structured to experiment with different stacks while following RESTful API principles.
- The inclusion of extensive Docker, Compose, CI/CD (via GitHub Actions workflows), and testing directories indicates a DevOps and test-first development approach.

d. Technologies and Frameworks:
- Component with its corresponding technology:
- Frontends: Next.js (with TypeScript) and HTMX with Go.
- Backends: Go-based REST API, and JavaScript/Node-based REST API.
- Databases: In Memory (simple stub) and Mongo.
- Testing: Cypress for E2E testing and BDD (Go) for system tests.
- Containers and orchestration by drawing a boundary or having an “Infrastructure” section, using Docker and docker-compose.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Infrastructure & Orchestration
    infra["Docker Compose Orchestration"]:::infraStyle

    %% Web Applications Tier
    subgraph "Web Applications"
        nextjs["Next.js Frontend"]:::webappStyle
        htmx["HTMX/Go Frontend"]:::webappStyle
        remix["Remix Frontend (Experimental)"]:::webappStyle
    end

    %% Backend Services Tier
    subgraph "Backend Services"
        goAPI["Go-based REST API"]:::backendStyle
        jsAPI["JS/Node-based REST API"]:::backendStyle
    end

    %% Databases Tier
    subgraph "Databases"
        inMemTasks["In-Memory DB (Tasks)"]:::dbStyle
        inMemAuth["In-Memory DB (Auth)"]:::dbStyle
        mongo["Mongo DB"]:::dbStyle
    end

    %% Testing Infrastructure Tier
    subgraph "Testing Infrastructure"
        cypress["Cypress E2E Tests"]:::testStyle
        bdd["BDD System Tests"]:::testStyle
    end

    %% Connections from Infrastructure to Web and Backend Tiers
    infra -->|"deploys"| nextjs
    infra -->|"deploys"| htmx
    infra -->|"deploys"| goAPI
    infra -->|"deploys"| jsAPI

    %% Frontend to Backend interactions
    nextjs -->|"API_call"| goAPI
    nextjs -->|"API_call"| jsAPI
    htmx  -->|"API_call"| goAPI
    htmx  -->|"API_call"| jsAPI
    remix -->|"API_call"| goAPI
    remix -->|"API_call"| jsAPI

    %% Backend to Database data persistence
    goAPI -->|"Data_persist"| inMemTasks
    goAPI -->|"Data_persist"| inMemAuth
    goAPI -->|"Data_persist"| mongo
    jsAPI -->|"Data_persist"| mongo

    %% Testing interactions
    cypress -->|"simulate"| nextjs
    cypress -->|"simulate"| htmx
    bdd     -->|"test"| goAPI
    bdd     -->|"test"| jsAPI

    %% Click Events
    click nextjs "https://github.com/tonitienda/kadai/tree/main/webapp-nextjs"
    click htmx "https://github.com/tonitienda/kadai/tree/main/webapp-htmx-go"
    click remix "https://github.com/tonitienda/kadai/tree/main/webapp-remix"
    click goAPI "https://github.com/tonitienda/kadai/tree/main/backend-rest-go"
    click jsAPI "https://github.com/tonitienda/kadai/tree/main/backend-rest-js"
    click inMemTasks "https://github.com/tonitienda/kadai/blob/main/backend-rest-go/pkg/tasks/db_in_memory.go"
    click inMemAuth "https://github.com/tonitienda/kadai/blob/main/backend-rest-go/pkg/authentication/db_in_memory.go"
    click mongo "https://github.com/tonitienda/kadai/blob/main/backend-rest-go/pkg/db/mongo.go"
    click cypress "https://github.com/tonitienda/kadai/tree/main/e2e-cypress"
    click bdd "https://github.com/tonitienda/kadai/tree/main/bdd-go"
    click infra "https://github.com/tonitienda/kadai/blob/main/compose.backend-go.yaml"

    %% Styles
    classDef infraStyle fill:#D2B4DE,stroke:#5B2C6F,stroke-width:2px;
    classDef webappStyle fill:#AED6F1,stroke:#2471A3,stroke-width:2px;
    classDef backendStyle fill:#A9DFBF,stroke:#1E8449,stroke-width:2px;
    classDef dbStyle fill:#F9E79F,stroke:#B9770E,stroke-width:2px;
    classDef testStyle fill:#F5CBA7,stroke:#BA4A00,stroke-width:2px;
```
