# twin-te/twinte-front architecture

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

- Interactive diagram: https://gitdiagram.com/twin-te/twinte-front
- Repository: https://github.com/twin-te/twinte-front

## Overview

##### Project Type and Purpose
- This is a front-end single-page application (SPA) built in Vue 3/TypeScript following Clean/Hexagonal Architecture (layers: adapter, application/use-cases, domain, infrastructure, presentation, UI).
- It’s packaged with Vite and deployed as a Docker container (Nginx) to Kubernetes (using Kustomize). It consumes a remote OpenAPI-defined backend (via aspida), plus Firebase for auth and localStorage for caching, and integrates with external donation/payment services.

##### Key Architectural Layers & Components
A. UI Layer (Vue components & pages)
- src/ui: Vue SFCs (views, components, hooks, store).
- storybook for component dev.
B. Presentation Layer
- src/presentation: presenters & viewmodels translate domain models into UI-friendly forms and vice versa.
C. Application Layer (Use­cases)
- src/application/usecases: orchestrate business operations (e.g., getCourses, sendFeedback).
- ports define repository interfaces (ICourseRepository, IUserRepository, etc.).
D. Domain Layer
- src/domain: core entities and value objects (Course, User, Schedule).
- domain-level errors, types, invariants.
E. Infrastructure Layer
- src/infrastructure/api (aspida): HTTP clients generated from OpenAPI spec to call remote backend.
- converters: map raw JSON to domain primitives.
- firebase: auth/session management.
- localstorage: caching layer implementing ports for offline state.
F. Adapter/Repository Layer
- src/repositories: concrete implementations of I*Repository (inMemory for dev, HTTP/Firebase for production).
G. Deployment & DevOps
- Dockerfiles (.devcontainer, production, staging).
- Kustomize manifests for Kubernetes (deployment/service).
- GitHub Actions workflows (CI, Docker build, deploy to staging/production).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CI/CD & Deployment
    subgraph "CI/CD & Deployment" 
        direction TB
        Dev((Developer)):::ci
        GH["GitHub Actions"]:::ci
        Registry((Container Registry)):::ci
        K8s["Kubernetes Cluster"]:::ci
        Nginx["Nginx (SPA Serving)"]:::ci
    end

    %% SPA Container Layers
    subgraph "SPA Container" 
        direction TB
        UI["UI Layer<br/>(Vue Components)"]:::frontend
        Presentation["Presentation Layer<br/>(Presenters & ViewModels)"]:::frontend
        subgraph "Application Layer"
            direction TB
            UseCases["Usecases"]:::domain
            Ports["Ports<br/>(Repository Interfaces)"]:::domain
        end
        Domain["Domain Layer<br/>(Entities & Value Objects)"]:::domain
        subgraph "Infrastructure Adapters"
            direction TB
            Aspida["aspida HTTP Client"]:::infra
            Converters["API Converters"]:::infra
            FirebaseAdapter["Firebase Adapter"]:::infra
            LocalStorageAdapter["LocalStorage Adapter"]:::infra
        end
        ReposDev["InMemory Repos"]:::infra
        ReposProd["HTTP/Firebase Repos"]:::infra
    end

    %% External Systems
    User((User)):::external
    Browser["Browser"]:::external
    BackendAPI[(Backend API)]:::external
    Firebase[(Firebase Auth/DB)]:::external
    LocalStorageStore[(LocalStorage)]:::external
    Payment[(Payment/Donation Service)]:::external

    %% Data Flows
    Dev --> GH --> Registry --> K8s --> Nginx --> UI
    User --> Browser --> Nginx
    UI -->|"UI events"| Presentation
    Presentation -->|"present data"| UseCases
    UseCases -->|"usecase call"| Domain
    Domain -->|"domain model"| Ports
    Ports --> ReposDev
    Ports --> ReposProd
    ReposDev --> Aspida
    ReposDev --> FirebaseAdapter
    ReposDev --> LocalStorageAdapter
    ReposProd --> Aspida
    ReposProd --> FirebaseAdapter
    ReposProd --> LocalStorageAdapter
    Aspida -->|"HTTP Request"| BackendAPI
    Converters --> Aspida
    FirebaseAdapter -->|"Auth/DB"| Firebase
    LocalStorageAdapter -->|"Cache R/W"| LocalStorageStore
    UseCases -->|"payment flow"| Payment

    %% Click Events
    click UI "https://github.com/twin-te/twinte-front/tree/main/src/ui"
    click Presentation "https://github.com/twin-te/twinte-front/tree/main/src/presentation"
    click UseCases "https://github.com/twin-te/twinte-front/tree/main/src/application/usecases"
    click Ports "https://github.com/twin-te/twinte-front/tree/main/src/application/ports"
    click Domain "https://github.com/twin-te/twinte-front/tree/main/src/domain"
    click Aspida "https://github.com/twin-te/twinte-front/tree/main/src/infrastructure/api/aspida"
    click Converters "https://github.com/twin-te/twinte-front/tree/main/src/infrastructure/api/converters"
    click FirebaseAdapter "https://github.com/twin-te/twinte-front/tree/main/src/infrastructure/firebase"
    click LocalStorageAdapter "https://github.com/twin-te/twinte-front/tree/main/src/infrastructure/localstorage"
    click ReposDev "https://github.com/twin-te/twinte-front/tree/main/src/repositories/development"
    click ReposProd "https://github.com/twin-te/twinte-front/tree/main/src/repositories/production"
    click GH "https://github.com/twin-te/twinte-front/blob/main/.github/workflows/ci.yml"
    click K8s "https://github.com/twin-te/twinte-front/blob/main/kustomize/kustomization.yaml"
    click Nginx "https://github.com/twin-te/twinte-front/blob/main/production_nginx.conf"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,color:#0366D6,stroke-width:1px;
    classDef domain fill:#E6FFEA,stroke:#28A745,color:#28A745,stroke-width:1px;
    classDef infra fill:#E0F7FA,stroke:#00796B,color:#00796B,stroke-width:1px;
    classDef ci fill:#FFF4E5,stroke:#FB8C00,color:#FB8C00,stroke-width:1px;
    classDef external fill:#F0F0F0,stroke:#6A737D,color:#6A737D,stroke-width:1px;
```
