# oliveryh/clear-habits architecture

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

- Interactive diagram: https://gitdiagram.com/oliveryh/clear-habits
- Repository: https://github.com/oliveryh/clear-habits

## Overview

##### Project type and purpose
- This is a full-stack, keyboard-driven task manager (“Clear Habits”) with two major client versions (v1 and v2) and a GraphQL/Postgres backend.
- v2 (“client-ui-thing”) is built on Nuxt 3 + UI Thing + Apollo/GraphQL.
- v1 (“client”) is built on Vue 2 + Quasar + Apollo/GraphQL.
- The backend (“server-postgraphile”) uses PostGraphile to auto-generate a GraphQL API on top of PostgreSQL.

##### File structure
- Top-level directories:
– client-ui-thing → Nuxt 3 / UI Thing frontend (v2)
– client → Vue 2 / Quasar frontend (v1)
– server-postgraphile → Node.js server using PostGraphile + migrations + tests
– conf → environment and deployment templates (Ansible, Nginx)
– fasthtml_apps & reflex_apps → supplementary Python/Reflex micro-apps (not part of core)
- Key patterns:
– “gql” folders and `.gql` files in both frontends → Apollo GraphQL client
– `migrations` + SQL → database schema evolution
– `.github/workflows` → CI/CD pipelines for test & deploy

##### README for additional insights
– v1: Quasar UI → Apollo → PostGraphile → PostgreSQL
– v2: Nuxt 3 + UI Thing → Apollo/Codegen → PostGraphile → PostgreSQL

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer (UI)
    subgraph "Frontend v2 (Primary)" 
        direction TB
        Nuxt["Nuxt 3 App"]:::frontend
        UIThing["UI Thing Config"]:::frontend
        Codegen["GraphQL Codegen (codegen.ts)"]:::frontend
        GQLUtils["GraphQL Client Utilities (gql/)"]:::frontend
        Pages["Pages & Components"]:::frontend
    end

    subgraph "Frontend v1 (Legacy)" 
        direction TB
        Vue2App["Vue 2 + Quasar App"]:::frontend
        QuasarConf["Quasar Config"]:::frontend
        ApolloConf["Apollo Client Config"]:::frontend
        GQLv1["GraphQL Queries & Fragments"]:::frontend
        VueComponents["Vue Components & Views"]:::frontend
    end

    %% API Layer
    subgraph "GraphQL API" 
        direction TB
        PostGraphile["PostGraphile Server"]:::api
        Hooks["Custom Build Hooks"]:::api
        Migrations["Database Migrations"]:::api
        Tests["Server Tests"]:::api
    end

    %% Persistence Layer
    PostgreSQL["PostgreSQL Database"]:::db

    %% DevOps Layer
    subgraph "CI/CD Pipelines" 
        direction TB
        TestCI["Test Workflow"]:::devops
        DeployV1["Deploy v1 Workflow"]:::devops
        DeployV2["Deploy v2 Workflow"]:::devops
    end

    subgraph "Deployment & Config" 
        direction TB
        Nginx["Nginx Config"]:::devops
        EnvProd[".env.production Templates"]:::devops
        Ansible["Ansible Playbooks"]:::devops
    end

    subgraph "Supplementary Micro-Apps" 
        direction TB
        FastHTML["FastHTML Apps"]:::devops
        Reflex["Reflex Apps"]:::devops
    end

    %% Connections
    Nuxt -->|HTTP GraphQL| PostGraphile
    Vue2App -->|HTTP GraphQL| PostGraphile
    PostGraphile -->|SQL Queries| PostgreSQL

    PostGraphile --> Hooks
    PostGraphile --> Migrations
    PostGraphile --> Tests

    TestCI -->|push & test| Vue2App
    TestCI -->|push & test| Vue2App
    DeployV2 -->|deploy v2| Nuxt
    DeployV1 -->|deploy v1| Vue2App
    DeployV1 -->|deploy backend| PostGraphile
    DeployV2 -->|deploy backend| PostGraphile

    DeployV1 --> Ansible
    DeployV2 --> Ansible
    Ansible --> Nginx
    Ansible --> EnvProd

    %% Click Events
    click Nuxt "https://github.com/oliveryh/clear-habits/tree/main/client-ui-thing/"
    click UIThing "https://github.com/oliveryh/clear-habits/blob/main/client-ui-thing/ui-thing.config.ts"
    click Codegen "https://github.com/oliveryh/clear-habits/blob/main/client-ui-thing/codegen.ts"
    click GQLUtils "https://github.com/oliveryh/clear-habits/tree/main/client-ui-thing/gql/"
    click Pages "https://github.com/oliveryh/clear-habits/tree/main/client-ui-thing/pages/"
    click Vue2App "https://github.com/oliveryh/clear-habits/tree/main/client/"
    click QuasarConf "https://github.com/oliveryh/clear-habits/blob/main/client/src/quasar.js"
    click ApolloConf "https://github.com/oliveryh/clear-habits/blob/main/client/apollo.config.js"
    click GQLv1 "https://github.com/oliveryh/clear-habits/tree/main/client/src/graphql/"
    click VueComponents "https://github.com/oliveryh/clear-habits/tree/main/client/src/components/"
    click PostGraphile "https://github.com/oliveryh/clear-habits/blob/main/server-postgraphile/server.js"
    click Hooks "https://github.com/oliveryh/clear-habits/blob/main/server-postgraphile/CustomBuildHooksPlugin.js"
    click Migrations "https://github.com/oliveryh/clear-habits/tree/main/server-postgraphile/migrations/"
    click Tests "https://github.com/oliveryh/clear-habits/tree/main/server-postgraphile/__tests__/"
    click TestCI "https://github.com/oliveryh/clear-habits/blob/main/.github/workflows/test.yml"
    click DeployV1 "https://github.com/oliveryh/clear-habits/blob/main/.github/workflows/deploy.yml"
    click DeployV2 "https://github.com/oliveryh/clear-habits/blob/main/.github/workflows/deploy_v2.yml"
    click Nginx "https://github.com/oliveryh/clear-habits/blob/main/conf/nginx.conf"
    click EnvProd "https://github.com/oliveryh/clear-habits/blob/main/conf/.env.production.j2"
    click Ansible "https://github.com/oliveryh/clear-habits/blob/main/conf/setup.yml"
    click FastHTML "https://github.com/oliveryh/clear-habits/tree/main/fasthtml_apps/"
    click Reflex "https://github.com/oliveryh/clear-habits/tree/main/reflex_apps/"

    %% Styles
    classDef frontend fill:#D6EAF8,stroke:#85C1E9,stroke-width:1px
    classDef api fill:#D5F5E3,stroke:#58D68D,stroke-width:1px
    classDef db fill:#FCF3CF,stroke:#F4D03F,stroke-width:1px
    classDef devops fill:#E5E8E8,stroke:#A6ACAF,stroke-width:1px
```
