# freenowtech/phrase-kotlin-client architecture

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

- Interactive diagram: https://gitdiagram.com/freenowtech/phrase-kotlin-client
- Repository: https://github.com/freenowtech/phrase-kotlin-client

## Overview

##### Project type and purpose
- This is a Kotlin library / CLI-style tool (“phrase-kotlin-client”) that provides a client and a sync task for the PhraseApp API v2.
- It’s not a frontend/backend web app but an SDK + build task that can be embedded in any JVM project (Spring Boot supported).

##### File structure
- Top-level: pom.xml, CI config (.github/workflows/mvn.yml), codecov.yml, LICENSE, README.md
- src/main/kotlin/com/freenow/apis/phraseapi/client → the core client interface, implementation, and config
- src/main/kotlin/com/freenow/apis/phraseapi/client/model → domain models (Project, Locale, Translation, etc.)
- src/main/kotlin/com/freenow/apis/phraseapi/task → the PhraseAppSyncTask that orchestrates the synchronization
- src/test/kotlin → unit and integration tests around the client and task
- No database, no UI, no webserver: core modules + integration with external API

##### Extract insights from README
- Purpose: fetch/sync translation resources from PhraseApp via REST API v2
- Usage: instantiate PhraseAppSyncTaskConfig, create PhraseAppSyncTask, call run()
- Supports Spring Boot 1.x/2.x (implying the client can be used as a Spring Boot task)

##### Main components & relationships
a. Components
- External Service: PhraseApp REST API v2
- Core Client Module
– PhraseApiClient interface
– PhraseApiClientImpl (HTTP calls)
– PhraseApiClientConfig (auth, URL)
– Model classes (Key, PhraseLocale, PhraseProject, Tags, Translation)
- Sync Orchestrator
– PhraseAppSyncTask (uses the client to fetch and process resources)
- Build & CI
– Maven (pom.xml)
– GitHub Actions workflow (mvn.yml)
– Codecov integration
- Tests
– Unit tests for client methods
– Integration tests against a mocked/real PhraseApp instance
b. Interactions
1. Developer code/config instantiates PhraseAppSyncTaskConfig
2. PhraseAppSyncTask calls PhraseApiClient methods (listProjects, listLocales, listKeys, fetchTranslations)
3. PhraseApiClientImpl issues HTTP requests to the external PhraseApp API endpoints
4. JSON responses are mapped to model objects
5. PhraseAppSyncTask writes or processes the fetched translations (e.g., saves to resources directory)
6. Maven runs tests and coverage in CI, reports back to GitHub and Codecov
c. Architectural patterns & design principles
- Separation of concerns: client interface vs implementation vs orchestration task
- Configuration-driven: client config object for injection
- Modular package structure (client vs models vs task)
- Test coverage: isolated unit tests + integration tests
d. Key technologies & libraries
- Kotlin (JVM language)
- Maven (build & dependency management)
- JUnit/TestNG or Kotlin test framework
- Jackson/Gson (JSON binding) or Spring’s RestTemplate/WebClient under the hood
- GitHub Actions (CI), Codecov

##### Details
- Client API call as separate interactions
- Configuration flow (where auth key and URL go)
- Test suite invoking the client in isolation vs integration tests against a stubbed/real API

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Actors
    Developer["Developer"]:::actor

    %% Internal Modules
    subgraph "Internal Modules"
        subgraph "Configuration"
            Config["PhraseApiClientConfig"]:::internal
        end
        subgraph "Orchestrator"
            SyncTask["PhraseAppSyncTask"]:::internal
        end
        subgraph "Client Module"
            APIInterface["PhraseApiClient"]:::internal
            APIImpl["PhraseApiClientImpl"]:::internal
            HTTPDefs["PhraseApi"]:::internal
        end
        subgraph "Models"
            Key["Key"]:::model
            Locale["PhraseLocale"]:::model
            Project["PhraseProject"]:::model
            Tags["Tags"]:::model
            Translation["Translation"]:::model
        end
    end

    %% External Service
    ExternalAPI["PhraseApp API v2"]:::external

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        Push["Code Push"]:::ci
        GitHubActions["GitHub Actions (mvn.yml)"]:::ci
        MavenTest["mvn test & package (pom.xml)"]:::ci
        Codecov["Codecov (codecov.yml)"]:::ci
    end

    %% Flows
    Developer -->|configures| Config
    Developer -->|push code| Push
    Config -->|provides settings| SyncTask
    SyncTask -->|calls| APIInterface
    APIInterface -->|implemented by| APIImpl
    APIImpl -->|uses HTTP defs| HTTPDefs
    HTTPDefs -->|sends requests to| ExternalAPI
    ExternalAPI -->|returns JSON| Key
    ExternalAPI -->|returns JSON| Locale
    ExternalAPI -->|returns JSON| Project
    ExternalAPI -->|returns JSON| Tags
    ExternalAPI -->|returns JSON| Translation
    Key -->|mapped to| SyncTask
    Locale -->|mapped to| SyncTask
    Project -->|mapped to| SyncTask
    Tags -->|mapped to| SyncTask
    Translation -->|mapped to| SyncTask

    Push --> GitHubActions
    GitHubActions --> MavenTest
    MavenTest --> Codecov

    %% Click events
    click Config "https://github.com/freenowtech/phrase-kotlin-client/blob/master/src/main/kotlin/com/freenow/apis/phraseapi/client/PhraseApiClientConfig.kt"
    click APIInterface "https://github.com/freenowtech/phrase-kotlin-client/blob/master/src/main/kotlin/com/freenow/apis/phraseapi/client/PhraseApiClient.kt"
    click APIImpl "https://github.com/freenowtech/phrase-kotlin-client/blob/master/src/main/kotlin/com/freenow/apis/phraseapi/client/PhraseApiClientImpl.kt"
    click HTTPDefs "https://github.com/freenowtech/phrase-kotlin-client/blob/master/src/main/kotlin/com/freenow/apis/phraseapi/client/PhraseApi.kt"
    click Key "https://github.com/freenowtech/phrase-kotlin-client/blob/master/src/main/kotlin/com/freenow/apis/phraseapi/client/model/Key.kt"
    click Locale "https://github.com/freenowtech/phrase-kotlin-client/blob/master/src/main/kotlin/com/freenow/apis/phraseapi/client/model/PhraseLocale.kt"
    click Project "https://github.com/freenowtech/phrase-kotlin-client/blob/master/src/main/kotlin/com/freenow/apis/phraseapi/client/model/PhraseProject.kt"
    click Tags "https://github.com/freenowtech/phrase-kotlin-client/blob/master/src/main/kotlin/com/freenow/apis/phraseapi/client/model/Tags.kt"
    click Translation "https://github.com/freenowtech/phrase-kotlin-client/blob/master/src/main/kotlin/com/freenow/apis/phraseapi/client/model/Translation.kt"
    click SyncTask "https://github.com/freenowtech/phrase-kotlin-client/blob/master/src/main/kotlin/com/freenow/apis/phraseapi/task/PhraseAppSyncTask.kt"
    click MavenTest "https://github.com/freenowtech/phrase-kotlin-client/blob/master/pom.xml"
    click GitHubActions "https://github.com/freenowtech/phrase-kotlin-client/blob/master/.github/workflows/mvn.yml"
    click Codecov "https://github.com/freenowtech/phrase-kotlin-client/blob/master/codecov.yml"

    %% Styles
    classDef actor fill:#eeeeee,stroke:#333,stroke-width:1px;
    classDef internal fill:#cce5ff,stroke:#339,stroke-width:1px;
    classDef model fill:#fff3cd,stroke:#996600,stroke-width:1px;
    classDef external fill:#f8d7da,stroke:#721c24,stroke-width:1px;
    classDef ci fill:#d4edda,stroke:#155724,stroke-width:1px;
```
