# noahlearner/teamwork-tasks-automation architecture

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

- Interactive diagram: https://gitdiagram.com/noahlearner/teamwork-tasks-automation
- Repository: https://github.com/noahlearner/teamwork-tasks-automation

## Overview

##### Project type and purpose
- This is a standalone, server-side Node.js automation tool, scheduled via cron, whose sole purpose is to build monthly recurring tasklists in Teamwork projects.
- At 00:00 on the first of each month it:
- Queries Teamwork’s Projects API for projects in designated categories
- Fetches each project’s roles via the Roles API
- Creates a new tasklist from a pre-built template and assigns each task based on role

##### File structure
- index.js – the single entry-point script
- package.json & package-lock.json – declare dependencies (node-fetch, moment, btoa)
- node_modules – installed libraries
- No frontend, no database, no microservices—just one service

##### README for additional insights
- All configuration (company name, API key, category IDs, role-to-user mappings, template IDs) is hard-coded in index.js.
- The script runs on Linux (e.g., Ubuntu on DigitalOcean) and is invoked by a cron entry:
`0 0 1 * * cd /root/auto && node index.js > /tmp/project.log`

##### Main components
a. Cron Scheduler (Linux cron daemon)
b. Ubuntu VM / DigitalOcean Droplet (host)
c. Node.js Runtime & index.js (the automation script)
d. Configuration block (company, key, catIds, role names, template IDs)
e. External Teamwork API (Projects, Roles, Tasklists endpoints)
f. Log sink (/tmp/project.log)

##### Relationships & interactions
- Cron scheduler → triggers → Node.js script
- Script reads its in-code config → initiates HTTP GET to /projects.json
- Receives project list → loops with delays → GET /{projectId}/roles.json
- Builds JSON payload → POST /{projectId}/tasklists.json
- Captures response → writes timestamped entries to the log file

##### Architectural patterns & design principles
- Scheduled batch processing (cron)
- Rate-limit management via incremental setTimeout delays
- Template method for constructing tasklist payloads
- Single responsibility: one script, one function

##### Elements
- Arrowheads showing call direction
- A side-attached “Config” block connected to the Script
- A “Log file” sink connected to the Script’s stdout

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Internal Components
    Cron["Cron Scheduler\n(0 0 1 * * cd /root/auto && node index.js > /tmp/project.log)"]:::internal
    Server["Ubuntu VM\n(DigitalOcean Droplet)"]:::internal
    Script["Node.js Script\n(index.js)"]:::internal
    Config["Configuration\n(company name, API key,\ncategory IDs, role mappings,\ntemplate IDs)"]:::config
    Dep["Dependencies\n(node-fetch, moment,\nbtoa)"]:::config
    Log["Log File\n/tmp/project.log"]:::log

    %% External Component
    API["Teamwork API\n(Projects, Roles,\nTasklists endpoints)"]:::external

    %% Layout
    Cron -->|"triggers"| Script
    Script -->|"reads config"| Config
    Script -->|"uses deps"| Dep
    Script -->|1. HTTP GET /projects| API
    Script -->|2. HTTP GET /roles| API
    Script -->|3. HTTP POST /tasklists| API
    Script -->|"writes logs"| Log

    %% Styles
    classDef internal fill:#cfe2f3,stroke:#036,stroke-width:1px
    classDef external fill:#f4cccc,stroke:#a00,stroke-width:1px
    classDef config fill:#d9d9d9,stroke:#666,stroke-width:1px
    classDef log fill:#d9d9d9,stroke:#666,stroke-width:1px

    %% Click Events
    click Script "https://github.com/noahlearner/teamwork-tasks-automation/blob/master/index.js"
    click Config "https://github.com/noahlearner/teamwork-tasks-automation/blob/master/index.js"
    click API "https://github.com/noahlearner/teamwork-tasks-automation/blob/master/index.js"
    click Dep "https://github.com/noahlearner/teamwork-tasks-automation/blob/master/package.json"
    click Cron "https://github.com/noahlearner/teamwork-tasks-automation/blob/master/README.md"
    click Log "https://github.com/noahlearner/teamwork-tasks-automation/blob/master/README.md"
```
