# okta/workflows-templates architecture

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

- Interactive diagram: https://gitdiagram.com/okta/workflows-templates
- Repository: https://github.com/okta/workflows-templates

## Overview

##### Project Type & Purpose
- This is an **open-source template library** for Okta Workflows: a GitHub repo that holds dozens of pre-built workflow “flopack” bundles plus metadata and scripts.  Developers submit new workflow templates here; CI/CD validates and publishes screenshots to S3/CloudFront for end-users to import into the Okta Workflows console.

##### File Structure Analysis
- **Top‐level files**:
- `.circleci/config.yml` → CI pipeline
- `package.json`/`package-lock.json` → Node.js dependencies & scripts
- `connectors.json` → master list of allowed connector names
- `workflows/` → each subfolder is a workflow template containing:
– `workflow.flopack` (exported bundle)
– `workflow.json` (metadata + details)
– `readme.md` (usage docs)
– optional `resources/` (screenshots)
- `scripts/json-details-scripts/` + `scripts/schema_validate.js`, `scripts/validate_release.sh` → CLI tools that populate and verify `workflow.json` details and enforce schema rules.
- `tutorial/` → contributor onboarding content

##### README Insights
- Contributors design in the Okta Workflows console → export _flopack_ → rename and drop into a folder → add metadata (`workflow.json`) and readme → run validation scripts locally and push → CircleCI runs `validate:schema`, `validate:release` → on success it auto-uploads screenshots to S3 (CloudFront CDN) and merges changes.

##### Components
a. **Source Control & Dev Environment**
- Developer machines (running Node.js / npm scripts)
- GitHub repository
b. **CI/CD Pipeline**
- CircleCI
- Validation scripts (`schema_validate.js`, `details_modifier.js`, `validate_release.sh`)
c. **Artifact Storage & Hosting**
- AWS S3 bucket (stores screenshots under `static/catalog/workflows/.../resources/...`)
- AWS CloudFront distribution (serves screenshot URLs)
d. **Runtime Consumer**
- Okta Workflows console (pulls metadata + flopack for end users)
e. **Configuration & Metadata**
- `connectors.json` (connector whitelist)
- `workflow.json` files in each template folder

##### Relationships & Data Flow
1. Developer commits new template files → pushes branch to GitHub
2. GitHub push triggers **CircleCI**
3. CircleCI executes:
- `npm install` → pulls Node.js scripts
- `scripts/schema_validate.js` → verifies JSON schemas
- `scripts/json-details-scripts/details_modifier.js` → auto-updates `details` in `workflow.json`
- `scripts/validate_release.sh` → release validation
- On success, uploads `resources/` screenshots to **S3**, invalidates/updates **CloudFront** cache
4. Merged changes make screenshots available at CloudFront URLs
5. End users browse the Okta Workflows catalog (metadata + screenshots pulled via CDN) and import `.flopack` into their tenant

##### Architectural Patterns & Principles
- **CI/CD pipeline**: automated validation, metadata generation, and asset deployment
- **Separation of Concerns**:
- Templates and metadata live under `workflows/`
- Validation/manipulation logic under `scripts/`
- CI orchestration in `.circleci/`
- **Immutable artifacts**: `.flopack` files + screenshot hashes ensure cache-busting
- **Static hosting**: metadata remains in Git; binary assets served via S3/CloudFront

##### Technologies & Frameworks
- Node.js (scripts, validation, metadata modification)
- JSON schemas for metadata (`workflow.json`, `connectors.json`)
- CircleCI (CI orchestration)
- AWS S3 & CloudFront (screenshot hosting + CDN)
- GitHub (source control)
- Okta Workflows (consumer of templates)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer / Local
    subgraph "Developer / Local"
        DW["Developer Workstation (Node.js)"]:::local
        subgraph "GitHub Repository"
            pj["package.json\npackage-lock.json"]:::local
            connectors["connectors.json"]:::local
            useCases["useCases.json"]:::local
            tutorial["tutorial/readme.md"]:::local
            subgraph scripts["scripts/"]
                schemaVal["schema_validate.js"]:::local
                detailsMod["json-details-scripts/details_modifier.js"]:::local
                releaseVal["validate_release.sh"]:::local
                schemaDef["workflow-schema.json"]:::local
                validator["json-details-scripts/details_validator.js"]:::local
                hasher["json-details-scripts/image_hasher.js"]:::local
                deleteDir["json-details-scripts/deleteDirec.js"]:::local
                utils["json-details-scripts/utils.js"]:::local
            end
            workflowsDir["workflows/"]:::local
            subgraph exampleFlow["workflows/add_inactive_users_to_marketo_list_for_remarketing/"]
                flopack["workflow.flopack"]:::local
                wfJson["workflow.json"]:::local
                readmeWF["readme.md"]:::local
                resourcesWF["resources/"]:::local
            end
        end
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        CI["CircleCI Pipeline"]:::ci
    end

    %% Cloud Infrastructure
    subgraph "Cloud Infrastructure"
        S3["AWS S3 Bucket"]:::cloud
        CF["CloudFront CDN"]:::cloud
    end

    %% External Consumer
    OKTA["Okta Workflows Console"]:::external

    %% Flows
    DW -->|"git push"| pj
    pj -->|"triggers build"| CI
    CI -->|"npm install"| pj
    CI -->|"schema validation"| schemaVal
    CI -->|"modify metadata"| detailsMod
    CI -->|"release validation"| releaseVal
    CI -->|"uses schema"| schemaDef
    CI -->|"utility scripts"| validator
    CI -->|"utility scripts"| hasher
    CI -->|"utility scripts"| deleteDir
    CI -->|"utility scripts"| utils
    CI -->|"upload screenshots"| S3
    S3 -->|"invalidate cache"| CF
    CF -->|"serve assets"| OKTA
    OKTA -->|"import .flopack"| flopack

    %% Click Events
    click CI "https://github.com/okta/workflows-templates/blob/master/.circleci/config.yml"
    click pj "https://github.com/okta/workflows-templates/blob/master/package.json"
    click connectors "https://github.com/okta/workflows-templates/blob/master/connectors.json"
    click useCases "https://github.com/okta/workflows-templates/blob/master/useCases.json"
    click tutorial "https://github.com/okta/workflows-templates/blob/master/tutorial/readme.md"
    click schemaVal "https://github.com/okta/workflows-templates/blob/master/scripts/schema_validate.js"
    click detailsMod "https://github.com/okta/workflows-templates/blob/master/scripts/json-details-scripts/details_modifier.js"
    click releaseVal "https://github.com/okta/workflows-templates/blob/master/scripts/validate_release.sh"
    click schemaDef "https://github.com/okta/workflows-templates/blob/master/scripts/workflow-schema.json"
    click validator "https://github.com/okta/workflows-templates/blob/master/scripts/json-details-scripts/details_validator.js"
    click hasher "https://github.com/okta/workflows-templates/blob/master/scripts/json-details-scripts/image_hasher.js"
    click deleteDir "https://github.com/okta/workflows-templates/blob/master/scripts/json-details-scripts/deleteDirec.js"
    click utils "https://github.com/okta/workflows-templates/blob/master/scripts/json-details-scripts/utils.js"
    click workflowsDir "https://github.com/okta/workflows-templates/tree/master/workflows/"
    click flopack "https://github.com/okta/workflows-templates/blob/master/workflows/add_inactive_users_to_marketo_list_for_remarketing/workflow.flopack"
    click wfJson "https://github.com/okta/workflows-templates/blob/master/workflows/add_inactive_users_to_marketo_list_for_remarketing/workflow.json"
    click readmeWF "https://github.com/okta/workflows-templates/blob/master/workflows/add_inactive_users_to_marketo_list_for_remarketing/readme.md"
    click resourcesWF "https://github.com/okta/workflows-templates/tree/master/workflows/add_inactive_users_to_marketo_list_for_remarketing/resources/"

    %% Styles
    classDef local fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef ci fill:#FFA500,stroke:#333,stroke-width:1px
    classDef cloud fill:#98FB98,stroke:#333,stroke-width:1px
    classDef external fill:#DDA0DD,stroke:#333,stroke-width:1px
```
