# kita99/narq architecture

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

- Interactive diagram: https://gitdiagram.com/kita99/narq
- Repository: https://github.com/kita99/narq

## Overview

##### Main Components

a) Core Components:
- Redis Database (central component)
- Worker System
- Timer System
- Web Interface/API Server
- Task Queue Manager
- Job Processing Pipeline

b) Integration Points:
- FastAPI Integration Interface
- Client Application Interface

##### Client Layer
- FastAPI integration point
- Client applications

##### Server Layer
- Web Interface (FastAPI-based)
- REST API endpoints

##### Core Processing Layer
- Worker system
- Timer system
- Task scheduler
- Job processor

##### Storage Layer
- Redis database
- Task queues
- Results storage

##### Key Relationships to Highlight

- Task submission flow (client → queue)
- Task processing flow (worker → task → result)
- Timer triggers (timer → task queue)
- API communications (web interface ↔ core system)

##### Specific Implementation Details

- Blue: Web interface components (server/templates, server/static)
- Green: Core processing components (worker.py, task.py)
- Yellow: Queue management (Redis)
- Orange: Timer system
- Purple: API endpoints (server/routes)

##### Special Features
- Cron task scheduling system
- Distributed task locking mechanism
- Task result storage and retrieval
- Queue management system

##### Architectural Patterns to Emphasize

Following patterns:
- Publisher/Subscriber pattern for task distribution
- MVC pattern in the web interface
- Async processing flow
- Distributed system communication

##### Component Details

- Main functionality
- Key dependencies
- Communication protocols
- Queue names and purposes

##### Additional Elements

Callouts for:
- Startup/shutdown hooks
- Task registration system
- Error handling flow
- Monitoring points

Key Considerations:
- Async nature of task processing
- How multiple workers can consume from multiple queues
- Timer's relationship with delayed and cron tasks
- Demonstrate how the web interface integrates with the core system

Remember to:
- Use clear, consistent symbols
- Version compatibility notes (Redis ≥ 5.0)
- Both standalone and integrated deployment options
- Scaling points in the architecture

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Client
        FA[FastAPI Integration]
        CA[Client Applications]
        EX["Example Implementation"]
    end

    subgraph "Web Interface"
        WS["Web Server"]
        API["API Server"]:::api
        TEMP["Templates"]:::ui
        STATIC["Static Assets"]:::ui
        
        subgraph "API Routes"
            JR["Job Routes"]:::api
            TR["Task Routes"]:::api
            WR["Worker Routes"]:::api
            RR["Result Routes"]:::api
        end
        
        MODELS["API Models"]:::model
        SCHEMAS["API Schemas"]:::model
    end

    subgraph "Core System"
        WORKER["Worker System"]:::core
        TASK["Task Processor"]:::core
        TIMER["Timer System"]:::core
        SIGNALS["Signal Handler"]:::core
        UTILS["Utilities"]:::core
        CLI["CLI Interface"]:::core
        CONST["Constants"]:::core
        ENUMS["Enumerations"]:::core
    end

    subgraph "Storage Layer"
        REDIS[(Redis DB)]:::db
        QUEUE[("Task Queues")]:::queue
        RESULTS[("Results Storage")]:::storage
    end

    %% Relationships
    FA --> API
    CA --> API
    EX --> API
    
    API --> WS
    WS --> TEMP
    WS --> STATIC
    
    API --> JR & TR & WR & RR
    JR & TR & WR & RR --> MODELS
    JR & TR & WR & RR --> SCHEMAS
    
    JR & TR & WR & RR --> WORKER
    WORKER --> TASK
    TASK --> QUEUE
    TIMER --> QUEUE
    QUEUE --> REDIS
    RESULTS --> REDIS
    
    WORKER --> SIGNALS
    WORKER --> UTILS
    WORKER --> CONST
    WORKER --> ENUMS
    
    CLI --> WORKER

    %% Styles
    classDef api fill:#f9f,stroke:#333
    classDef ui fill:#9cf,stroke:#333
    classDef core fill:#9f9,stroke:#333
    classDef db fill:#ff9,stroke:#333
    classDef queue fill:#f90,stroke:#333
    classDef storage fill:#fc9,stroke:#333
    classDef model fill:#c9f,stroke:#333

    %% Click Events
    click WORKER "https://github.com/kita99/narq/blob/master/narq/worker.py"
    click TASK "https://github.com/kita99/narq/blob/master/narq/task.py"
    click WS "https://github.com/kita99/narq/blob/master/narq/server/app.py"
    click JR "https://github.com/kita99/narq/blob/master/narq/server/routes/job.py"
    click TR "https://github.com/kita99/narq/blob/master/narq/server/routes/task.py"
    click WR "https://github.com/kita99/narq/blob/master/narq/server/routes/worker.py"
    click RR "https://github.com/kita99/narq/blob/master/narq/server/routes/result.py"
    click TEMP "https://github.com/kita99/narq/tree/master/narq/server/templates/"
    click STATIC "https://github.com/kita99/narq/tree/master/narq/server/static/"
    click MODELS "https://github.com/kita99/narq/blob/master/narq/server/models.py"
    click SCHEMAS "https://github.com/kita99/narq/blob/master/narq/server/schemas.py"
    click CONST "https://github.com/kita99/narq/blob/master/narq/constants.py"
    click ENUMS "https://github.com/kita99/narq/blob/master/narq/enums.py"
    click SIGNALS "https://github.com/kita99/narq/blob/master/narq/signals.py"
    click EX "https://github.com/kita99/narq/blob/master/examples/app.py"
    click CLI "https://github.com/kita99/narq/blob/master/narq/cli.py"
    click UTILS "https://github.com/kita99/narq/blob/master/narq/utils.py"
```
