# ccextractor/ccsync architecture

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

- Interactive diagram: https://gitdiagram.com/ccextractor/ccsync
- Repository: https://github.com/ccextractor/ccsync

## Overview

##### Project Type & Purpose
- CCSync is a full-stack application aimed at synchronizing and managing tasks for Taskwarrior 3.0+ users. The project offers a RESTful API server (backend), a web-based user interface (frontend), and integration with a Taskwarrior Flutter app for mobile users.
- The backend (written in Go) communicates with local Taskwarrior clients and the external Taskchampion-sync-server container to manage task synchronization, while the frontend (built with modern JavaScript/TypeScript using Vite, React, Tailwind CSS, etc.) serves as a user-friendly interface.

##### Analyzing the File Structure
- The top-level directories are “backend” and “frontend”, each with its own README and Dockerfile. Additional directories (.github, configuration files, docker-compose.yml) indicate CI/CD pipelines and container orchestration.
- Under “backend”, folders like controllers, middleware, models, and utils reveal the REST API logic, business rules (controllers handling operations like add, edit, delete, complete tasks), cross-cutting concerns (e.g. rate limiting middleware), and utility functions (including those supporting Taskwarrior command integrations).
- The “frontend” folder contains the complete structure of a modern web app (components, assets, configuration files, tests, and styles) that serves the CCSync UI. There is also evidence of unit testing and clear separation between UI segments for home, landing, and tasks.
- The docker-compose.yml and Dockerfiles for each component indicate that the system is likely containerized, ensuring that each part (backend and web UI) can be deployed independently yet interact through defined interfaces.

##### Key Components
a. Backend Server:
- RESTful API service, implemented in Go.
- Sub-components such as controllers (handling task operations), middleware (e.g., rate limiting), and models (defining the task structure and request formats).
- Specialized utilities that execute Taskwarrior commands and manage UUID/encryption functionalities.
b. Frontend Web UI:
- Single-page application powered by modern JavaScript/TypeScript (React/Vite).
- Sub-components or modules (e.g., HomeComponents, LandingComponents, UI kit components) that constitute different screens and functionalities (e.g., Navbar, Footer, TaskViews).
c. Taskwarrior Flutter App:
- Even though its code isn’t part of this repository, represent it as an external client that consumes the backend API.
d. External Services/Containers:
- Taskchampion-sync-server container as an external dependency which interacts with the backend.
- Optionally, include any database or persistent storage if applicable (even if not explicitly visible in the file structure, consider its role in synchronization, command execution, or state management).
e. Deployment & CI/CD:
- Docker containers for both frontend and backend (derived from the Dockerfile and docker-compose.yml).
- Code quality/CI pipelines (GitHub workflows for linting and formatting) as part of the continuous integration aspect.

##### Relationships and Interactions
- Similarly, show the Taskwarrior Flutter App connecting to the Backend API.
- Backend-internal interactions where controllers make calls to system utilities (for instance, to execute Taskwarrior commands) and then interact with the Taskchampion-sync-server.
- If applicable, denote container orchestration: the docker-compose setup ties the individual containers together.

##### Architectural Patterns & Design Principles
- Separation of concerns: UI (frontend) vs. business logic and API (backend).
- Use of middleware for cross-cutting policies (like rate limiting).
- Use of containerization and CI/CD best practices as extracted from the .github and Docker configurations.
- RESTful API design, which enables multiple client types (web UI and mobile Flutter app) to interact with the backend in a unified way.

- That containerization (via Docker) and CI/CD workflows are part of your deployment architecture.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        FE["Frontend Web UI"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        BAS["Backend API Server"]:::backend
        BAS --> RCT["REST Controllers"]:::controllers
        BAS --> MW["Middleware (Rate Limiting)"]:::middleware
        BAS --> DM["Data Models"]:::models
        BAS --> TWU["Taskwarrior Command Utilities"]:::utilities
    end

    %% External Clients and Services
    TFA["Taskwarrior Flutter App"]:::external
    TCS["Taskchampion Sync Server"]:::external

    %% Deployment & CI/CD Components
    subgraph "Deployment & CI/CD"
        BDF["Backend Dockerfile"]:::deployment
        FDF["Frontend Dockerfile"]:::deployment
        DC["Docker Compose"]:::deployment
        CICD["CI/CD Pipelines"]:::cicd
    end

    %% Relationships between layers and components
    FE -->|"API_calls"| BAS
    TFA -->|"API_requests"| BAS
    BAS -->|"sync_tasks"| TCS
    RCT -->|"executes"| TWU

    %% Deployment orchestration
    CICD -->|"triggers"| DC
    DC -->|"orchestrates"| BAS
    DC -->|"orchestrates"| FE

    %% Classes for styling
    classDef frontend fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef backend fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef controllers fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef middleware fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef models fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef utilities fill:#e2e3e5,stroke:#41464b,stroke-width:2px;
    classDef external fill:#fefefe,stroke:#818182,stroke-width:2px,stroke-dasharray: 5 5;
    classDef deployment fill:#d6d8db,stroke:#1b1e21,stroke-width:2px;
    classDef cicd fill:#c3e6cb,stroke:#155724,stroke-width:2px;

    %% Click Events
    click FE "https://github.com/ccextractor/ccsync/tree/main/frontend/"
    click BAS "https://github.com/ccextractor/ccsync/tree/main/backend/"
    click RCT "https://github.com/ccextractor/ccsync/tree/main/backend/controllers/"
    click MW "https://github.com/ccextractor/ccsync/blob/main/backend/middleware/ratelimit.go"
    click DM "https://github.com/ccextractor/ccsync/tree/main/backend/models/"
    click TWU "https://github.com/ccextractor/ccsync/tree/main/backend/utils/tw/"
    click BDF "https://github.com/ccextractor/ccsync/tree/main/backend/Dockerfile"
    click FDF "https://github.com/ccextractor/ccsync/tree/main/frontend/Dockerfile"
    click DC "https://github.com/ccextractor/ccsync/blob/main/docker-compose.yml"
    click CICD "https://github.com/ccextractor/ccsync/tree/main/.github/workflows/"
```
