# talgaon4/promptcraft architecture

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

- Interactive diagram: https://gitdiagram.com/talgaon4/promptcraft
- Repository: https://github.com/talgaon4/promptcraft

## Overview

##### Project Type and Purpose
- This is a backend-only REST API service written in Python.
- Its goal is to receive AI prompts, collect user feedback, and automatically optimize prompts (via background jobs).
- Key external dependencies: PostgreSQL (persistent storage) and Redis (job queue).

##### File Structure
Top-level:
- src/main.py – entry point, likely bootstraps FastAPI or similar.
- src/api – routes/controllers and error handling.
- src/services – business-logic layer (PromptService, FeedbackService, HealthService, etc.).
- src/database – DB connection and schema.
- src/models – ORM or data models.
Supporting:
- config.py – central configuration (DB URL, Redis URL, etc.).
- requirements.txt – tech stack (FastAPI/Uvicorn, SQLAlchemy, Celery/RQ).
Tests folder – validates each service and route.

##### Extract Architecture Insights from README
- REST endpoints for prompts, feedback, health checks, instances.
- Background jobs (using Redis) for long-running optimization tasks.
- Uses PostgreSQL for storing prompts, feedback, instances.

##### Main System Components
a. API Layer
– FastAPI (src/main.py + src/api/routes)
– Error handlers & request/response schemas
b. Service Layer
– PromptService, FeedbackService, HealthService, BaseService
– Export utilities for data export
c. Data Layer
– PostgreSQL database (schema.sql, database.py)
– ORM models (models.py)
d. Background Job Processor
– Redis-backed queue (e.g., Celery or RQ; implied by Redis requirement)
– Worker processes pulling tasks from queue to optimize prompts
e. External Clients
– Frontend or CLI clients issuing HTTP requests
– Automated scripts or other services

##### Component Interactions
- Client → HTTP(S) → API Layer
- API routes validate via Pydantic schemas → delegate to Service Layer
- Service Layer → read/write → PostgreSQL (through database.py & models)
- For optimization tasks: Service enqueues job → Redis queue
- Worker (“instance” route or separate process) dequeues from Redis → performs compute → writes results back to DB
- HealthService → simple DB/Redis pings

##### Architectural Patterns & Principles
– Layered architecture (API → Services → Database)
– Separation of concerns:
- Routing & validation in src/api
- Business logic in src/services
- Data access in src/database + src/models
– Asynchronous background processing (decouples heavy tasks via Redis queue)
– Configuration via environment variables (.env) for 12-factor compliance

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    Client["Client"]:::external

    %% Configuration
    subgraph "Configuration"
        Config["Config"]:::config
    end

    %% API Layer
    subgraph "API Layer"
        API["FastAPI App"]:::compute
        Routes["Routes"]:::compute
        ErrorHandlers["Error Handlers"]:::compute
        Schemas["Schemas"]:::compute
    end

    %% Service Layer
    subgraph "Service Layer"
        PromptService["PromptService"]:::compute
        FeedbackService["FeedbackService"]:::compute
        HealthService["HealthService"]:::compute
        BaseService["BaseService"]:::compute
        ExportUtils["Export Utils"]:::compute
    end

    %% Data Layer
    subgraph "Data Layer"
        DBConn["DB Connection"]:::database
        SchemaSQL["Schema SQL"]:::database
        Models["ORM Models"]:::database
        PostgreSQL["PostgreSQL"]:::database
        Redis["Redis Queue"]:::database
    end

    %% Worker
    Worker["Worker Process"]:::compute

    %% Connections
    Client -->|"HTTP(S)"| API
    Config --> API
    Config --> DBConn
    Config --> Redis
    Config --> Worker

    API --> Routes
    API --> ErrorHandlers
    API --> Schemas

    Routes -->|"calls"| PromptService
    Routes -->|"calls"| FeedbackService
    Routes -->|"calls"| HealthService

    PromptService -->|"SQLAlchemy"| DBConn
    FeedbackService -->|"SQLAlchemy"| DBConn
    HealthService -->|"ping"| DBConn
    HealthService -->|"ping"| Redis

    PromptService -->|"enqueue"| Redis
    FeedbackService -->|"enqueue"| Redis

    Redis -->|"Pub/Sub"| Worker
    Worker -->|"writes"| DBConn

    DBConn --> Models
    DBConn --> SchemaSQL
    DBConn --> PostgreSQL

    class Client external
    class API,Routes,ErrorHandlers,Schemas,PromptService,FeedbackService,HealthService,BaseService,ExportUtils,Worker compute
    class DBConn,SchemaSQL,Models,PostgreSQL,Redis database
    class Config config

    %% Click Events
    click Config "https://github.com/talgaon4/promptcraft/blob/master/src/config.py"
    click API "https://github.com/talgaon4/promptcraft/blob/master/src/main.py"
    click Routes "https://github.com/talgaon4/promptcraft/tree/master/src/api/routes/"
    click ErrorHandlers "https://github.com/talgaon4/promptcraft/blob/master/src/api/error_handlers.py"
    click Schemas "https://github.com/talgaon4/promptcraft/tree/master/src/api/schemas/"
    click PromptService "https://github.com/talgaon4/promptcraft/blob/master/src/services/prompt_service.py"
    click FeedbackService "https://github.com/talgaon4/promptcraft/blob/master/src/services/feedback_service.py"
    click HealthService "https://github.com/talgaon4/promptcraft/blob/master/src/services/health_service.py"
    click BaseService "https://github.com/talgaon4/promptcraft/blob/master/src/services/base_service.py"
    click ExportUtils "https://github.com/talgaon4/promptcraft/blob/master/src/services/export_utils.py"
    click DBConn "https://github.com/talgaon4/promptcraft/blob/master/src/database/database.py"
    click SchemaSQL "https://github.com/talgaon4/promptcraft/blob/master/src/database/schema.sql"
    click Models "https://github.com/talgaon4/promptcraft/blob/master/src/models/models.py"

    %% Styles
    classDef external fill:#FFA500,stroke:#333,color:#000
    classDef compute fill:#D0E6FF,stroke:#333,color:#000
    classDef database fill:#D0FFD6,stroke:#333,color:#000
    classDef config fill:#F0D6FF,stroke:#333,color:#000
```
