# kavyashah26/justrun architecture

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

- Interactive diagram: https://gitdiagram.com/kavyashah26/justrun
- Repository: https://github.com/kavyashah26/justrun

## Overview

##### Project Type and Purpose
- JustRun is a full-stack, cloud-native, serverless microservices platform for scheduling and automating HTTP-based tasks.
- It consists of multiple backend Spring-Boot services (AuthService, TaskManagementService, CronScanner, TaskExecutionService) and a Next.js frontend.
- It leverages AWS DynamoDB, SQS, and CloudWatch for persistence, queuing, and logging.

##### High-Level Architecture Components
a. Frontend (Next.js)
- Handles user authentication, task creation, visualization, and workflow management
- Communicates with backend services via REST API calls
b. AuthService
- Manages user sign-up, login, JWT issuance, and API key validation
- Provides an authentication gateway for all other services
c. TaskManagementService
- CRUD operations for tasks and task chains
- Validates user permissions and task data
d. CronScanner
- Periodically polls DynamoDB for due ROOT tasks based on cron expressions
- Claims tasks and enqueues them into SQS priority queues (HIGH, NORMAL, LOW)
e. TaskExecutionService
- Listens to SQS queues, dequeues tasks, executes HTTP requests
- Handles retries with exponential backoff, logs each attempt to DynamoDB
- Triggers chained tasks upon completion or failure
f. AWS Services
- DynamoDB: Stores users, tasks, task chains, execution logs
- SQS: Three priority queues for task dispatch
- CloudWatch: Centralized metrics and logs

##### Component Interactions and Data Flow
1. User opens frontend → sends login or API calls to AuthService (via API Gateway)
2. On success, frontend stores JWT and calls TaskManagementService to create/edit tasks
3. TaskManagementService writes task metadata into DynamoDB
4. CronScanner (cron scheduler service) periodically:
– Scans DynamoDB for due ROOT tasks
– Marks the task as claimed (concurrency control)
– Pushes a message to the appropriate SQS queue
5. TaskExecutionService workers poll SQS queues:
– Dequeue task message → execute HTTP call → on success/failure, record in DynamoDB
– If chained tasks exist, enqueue them back into SQS or DynamoDB for next run
6. Frontend or other services can fetch execution logs or task status from TaskManagementService

##### Architectural Patterns and Principles
- Microservices: Each backend service is independently deployable (own repo, Dockerfile, configs).
- Serverless/Cloud-native: Uses managed AWS services to avoid server management.
- Event-driven: SQS as event bus for task dispatching and decoupling scanner from execution.
- Resilience: JWT-based security, retries with backoff, concurrency control in DynamoDB.
- Scalability: Each service autoscaled; multiple TaskExecutionService workers can consume from SQS.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Layer
    subgraph "User Layer"
        User["User Browser"]:::user
    end

    %% Edge/API Layer
    subgraph "Edge/API Layer"
        Frontend["Next.js Frontend"]:::frontend
        APIGW["API Gateway"]:::gateway
    end

    %% Services Layer
    subgraph "Services Layer"
        AuthService["AuthService"]:::service
        Auth_AwsConfig["AwsConfig.java"]:::config
        Auth_SecurityConfig["SecurityConfig.java"]:::config
        Auth_Controller["AuthController.java"]:::controller
        Auth_Repo["UserRepository.java"]:::repo
        Auth_PostHog["PostHogService.java"]:::service
        TaskManagementService["TaskManagementService"]:::service
        TM_AwsConfig["AwsConfig.java"]:::config
        TM_SecurityConfig["SecurityConfig.java"]:::config
        TM_CorsConfig["CorsConfig.java"]:::config
        TM_Controller["TaskController.java"]:::controller
        TM_Repo["TaskRepository.java"]:::repo
        TM_PostHog["PostHogService.java"]:::service
        CronScanner["CronScanner"]:::service
        CS_AwsConfig["AwsConfig.java"]:::config
        CS_Service["CronScannerService.java"]:::service
        CS_QueueService["QueueService.java"]:::service
        CS_Repo["TaskRepository.java"]:::repo
        CS_PostHog["PostHogService.java"]:::service
        TaskExecutionService["TaskExecutionService"]:::service
        TE_AwsConfig["AwsConfig.java"]:::config
        TE_SecurityConfig["SecurityConfig.java"]:::config
        TE_Controller["TaskController.java"]:::controller
        TE_QueueService["QueueService.java"]:::service
        TE_Worker["QueueWorker.java"]:::service
        TE_Repo["TaskExecutionRepository.java"]:::repo
        TE_PostHog["PostHogService.java"]:::service
    end

    %% AWS Services
    subgraph "AWS Services"
        DynamoDB["DynamoDB"]:::aws
        SQS_H["SQS Priority High"]:::aws
        SQS_N["SQS Priority Normal"]:::aws
        SQS_L["SQS Priority Low"]:::aws
        CloudWatch["CloudWatch"]:::aws
    end

    ExternalAPI["External HTTP Target"]:::external

    %% Relationships
    User -->|"interacts with"| Frontend
    Frontend -->|"REST API calls"| APIGW
    APIGW -->|"Auth request"| AuthService
    APIGW -->|"Task API call"| TaskManagementService
    AuthService -->|"validates JWT/API key"| TaskManagementService
    TaskManagementService -->|"writes task metadata"| DynamoDB
    CronScanner -->|"scans due tasks"| DynamoDB
    CronScanner -->|"enqueues messages"| SQS_H
    CronScanner -->|"enqueues messages"| SQS_N
    CronScanner -->|"enqueues messages"| SQS_L
    TaskExecutionService -->|"dequeues tasks"| SQS_H
    TaskExecutionService -->|"dequeues tasks"| SQS_N
    TaskExecutionService -->|"dequeues tasks"| SQS_L
    TaskExecutionService -->|"executes HTTP call"| ExternalAPI
    TaskExecutionService -->|"logs execution"| DynamoDB
    TaskExecutionService -->|"enqueues chained tasks"| SQS_H
    AuthService --- CloudWatch
    TaskManagementService --- CloudWatch
    CronScanner --- CloudWatch
    TaskExecutionService --- CloudWatch

    %% Click Events
    click Frontend "https://github.com/kavyashah26/justrun/tree/main/frontend/"
    click AuthService "https://github.com/kavyashah26/justrun/tree/main/backend/AuthService/"
    click TaskManagementService "https://github.com/kavyashah26/justrun/tree/main/backend/TaskManagementService/"
    click CronScanner "https://github.com/kavyashah26/justrun/tree/main/backend/CronScanner/"
    click TaskExecutionService "https://github.com/kavyashah26/justrun/tree/main/backend/TaskExecutionService/"
    click Auth_AwsConfig "https://github.com/kavyashah26/justrun/blob/main/backend/AuthService/src/main/java/org/JustRun/AuthService/Config/AwsConfig.java"
    click Auth_SecurityConfig "https://github.com/kavyashah26/justrun/blob/main/backend/AuthService/src/main/java/org/JustRun/AuthService/Config/SecurityConfig.java"
    click Auth_Controller "https://github.com/kavyashah26/justrun/blob/main/backend/AuthService/src/main/java/org/JustRun/AuthService/Controller/AuthController.java"
    click Auth_Repo "https://github.com/kavyashah26/justrun/blob/main/backend/AuthService/src/main/java/org/JustRun/AuthService/Repository/UserRepository.java"
    click Auth_PostHog "https://github.com/kavyashah26/justrun/blob/main/backend/AuthService/src/main/java/org/JustRun/AuthService/Service/PostHogService.java"
    click TM_AwsConfig "https://github.com/kavyashah26/justrun/blob/main/backend/TaskManagementService/src/main/java/org/JustRun/TaskManagementService/Config/AwsConfig.java"
    click TM_SecurityConfig "https://github.com/kavyashah26/justrun/blob/main/backend/TaskManagementService/src/main/java/org/JustRun/TaskManagementService/Config/SecurityConfig.java"
    click TM_CorsConfig "https://github.com/kavyashah26/justrun/blob/main/backend/TaskManagementService/src/main/java/org/JustRun/TaskManagementService/Config/CorsConfig.java"
    click TM_Controller "https://github.com/kavyashah26/justrun/blob/main/backend/TaskManagementService/src/main/java/org/JustRun/TaskManagementService/Controller/TaskController.java"
    click TM_Repo "https://github.com/kavyashah26/justrun/blob/main/backend/TaskManagementService/src/main/java/org/JustRun/TaskManagementService/Repository/TaskRepository.java"
    click TM_PostHog "https://github.com/kavyashah26/justrun/blob/main/backend/TaskManagementService/src/main/java/org/JustRun/TaskManagementService/Service/PostHogService.java"
    click CS_AwsConfig "https://github.com/kavyashah26/justrun/blob/main/backend/CronScanner/src/main/java/org/JustRun/CronScannerService/Config/AwsConfig.java"
    click CS_Service "https://github.com/kavyashah26/justrun/blob/main/backend/CronScanner/src/main/java/org/JustRun/CronScannerService/Service/CronScannerService.java"
    click CS_QueueService "https://github.com/kavyashah26/justrun/blob/main/backend/CronScanner/src/main/java/org/JustRun/CronScannerService/Service/QueueService.java"
    click CS_Repo "https://github.com/kavyashah26/justrun/blob/main/backend/CronScanner/src/main/java/org/JustRun/CronScannerService/Repository/TaskRepository.java"
    click CS_PostHog "https://github.com/kavyashah26/justrun/blob/main/backend/CronScanner/src/main/java/org/JustRun/CronScannerService/Service/PostHogService.java"
    click TE_AwsConfig "https://github.com/kavyashah26/justrun/blob/main/backend/TaskExecutionService/src/main/java/org/JustRun/TaskExecutionService/Config/AwsConfig.java"
    click TE_SecurityConfig "https://github.com/kavyashah26/justrun/blob/main/backend/TaskExecutionService/src/main/java/org/JustRun/TaskExecutionService/Config/SecurityConfig.java"
    click TE_Controller "https://github.com/kavyashah26/justrun/blob/main/backend/TaskExecutionService/src/main/java/org/JustRun/TaskExecutionService/Controller/TaskController.java"
    click TE_QueueService "https://github.com/kavyashah26/justrun/blob/main/backend/TaskExecutionService/src/main/java/org/JustRun/TaskExecutionService/service/QueueService.java"
    click TE_Worker "https://github.com/kavyashah26/justrun/blob/main/backend/TaskExecutionService/src/main/java/org/JustRun/TaskExecutionService/Worker/QueueWorker.java"
    click TE_Repo "https://github.com/kavyashah26/justrun/blob/main/backend/TaskExecutionService/src/main/java/org/JustRun/TaskExecutionService/Repository/TaskExecutionRepository.java"
    click TE_PostHog "https://github.com/kavyashah26/justrun/blob/main/backend/TaskExecutionService/src/main/java/org/JustRun/TaskExecutionService/service/PostHogService.java"

    %% Styles
    classDef user fill:#a2d5c6,stroke:#2a7f62,color:#000
    classDef frontend fill:#c2f0fc,stroke:#037d8c,color:#000
    classDef gateway fill:#ffd966,stroke:#d79e00,color:#000
    classDef service fill:#d5e8d4,stroke:#82b366,color:#000
    classDef aws fill:#f9cb9c,stroke:#e69138,color:#000
    classDef external fill:#eeeeee,stroke:#888888,color:#000
    classDef config fill:#e1d5e7,stroke:#9673a6,color:#000
    classDef controller fill:#ffe599,stroke:#bf9000,color:#000
    classDef repo fill:#f4cccc,stroke:#cc0000,color:#000
```
