# aytzey/codetopromptgenerator architecture

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

- Interactive diagram: https://gitdiagram.com/aytzey/codetopromptgenerator
- Repository: https://github.com/aytzey/codetopromptgenerator

## Overview

##### Project Type and Purpose
- This is a full-stack application (“Code to Prompt Generator Tool”) whose frontend is built with Next.js/React/TypeScript and whose backend is a Python Flask API.
- Purpose: allow users to scan a local file tree, select/exclude files, compose meta-prompts, and bundle everything (including file contents) into a single payload for use with LLMs.

##### File Structure
- Top level
- Configuration: package.json, tsconfig.json, next.config.js, ports.ini, .env.local
- CI/CD: .github/workflows/ci.yml
- Scripts: start.js/.bat/.sh, postinstall.js, autotest.js
- Frontend
- pages/ → Next.js entrypoints (_app.tsx, index.tsx)
- components/ → reusable UI primitives (shadcn/ui wrappers, ErrorBoundary)
- views/ → higher-level screens and panels (FileTreeView, FolderPickerView, etc.)
- stores/ → Zustand stores for application state (useAppStore, useTodoStore, etc.)
- services/ → client-side API wrappers and React service hooks
- lib/ → shared utilities and custom React hooks (useDebounce, useHomePageLogic, etc.)
- styles/, tailwind.config.js → styling
- Backend (python_backend/)
- app.py → Flask app factory, routing setup
- controllers/ → REST endpoints (file scanning, todos, meta-prompts, projects, exclusions, etc.)
- services/ → business logic for each domain
- repositories/ → file‐system-based persistence
- models/ → request/response schemas and data models
- utils/ → helper modules (path_utils, response_utils)
- requirements.txt, virtual-env under python_backend/venv
- Testing & CI
- scripts/autotest.js → automated end-to-end smoke tests
- .github/workflows/ci.yml → runs tests on push/PR

##### README for Architectural Insights
- It confirms a REST API on Flask (CORS enabled) at port 5000, consumed by the Next.js frontend at port 3000.
- It outlines features that map directly to backend controllers and frontend views/service hooks.
- No external database—persistence is file-system or in-memory for to-dos; meta-prompts saved as text files.

a. Main Components
- Frontend Application (Next.js + React + Tailwind + shadcn/ui)
- Backend API Server (Flask + Flask-CORS)
- Local File System (scanned directories, meta-prompt files, exclusions config)
- State Management (Zustand stores)
- Client-side API Layer (services/apiService.ts + service hooks)
- CI Pipeline (GitHub Actions)
b. Relationships & Data Flows
1. User interacts with UI components (views, components)
2. Components dispatch actions to Zustand stores or call service hooks
3. Service hooks use apiService to send HTTP requests to Flask endpoints
4. Flask controllers delegate to services → repositories → file system
5. Responses return JSON payloads (directory tree, file contents, todos, etc.)
6. Frontend updates UI/store, renders new state
7. “Copy to Clipboard” aggregates store state and selected file contents purely on the client
8. CI pipeline triggers on push, runs autotest.js against running servers
c. Architectural Patterns & Principles
- MVC-style layering in backend (Controller → Service → Repository)
- Component-driven UI with atomic shadcn/ui primitives
- Hook-based data fetching (service hooks)
- Global state with lightweight stores (Zustand)
- Clear separation of concerns: UI vs API vs persistence
d. Key Technologies & Frameworks
- Next.js, React, TypeScript, Tailwind CSS, shadcn/ui
- Zustand for state
- Axios or fetch in apiService (services/apiService.ts)
- Flask + Flask-CORS in Python 3.7+
- GitHub Actions for CI

##### Detail Is Key
- Break out sub-components when they add clarity (e.g., split React Views vs Components vs Stores vs Service Hooks).
- Configuration files (ports.ini) as part of the startup flow.
- Script orchestration (start.js → spawns Next.js + Flask).
- Folder-scan flow separately from the todo/meta-prompt flow to demonstrate parallel features.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Zone
    subgraph "Frontend" 
        direction TB
        NextApp["Next.js App<br>(_app.tsx)"]:::frontend
        MainPage["Main Page<br>(index.tsx)"]:::frontend
        Views["React Views<br>(views/)"]:::frontend
        UIComponents["UI Components<br>(components/ui/)"]:::frontend
        ErrorBoundary["Error Boundary<br>(ErrorBoundary.tsx)"]:::frontend
        Stores["Zustand Stores<br>(stores/)"]:::frontend
        APIService["apiService.ts"]:::frontend
        ServiceHooks["Service Hooks<br>(*ServiceHooks.ts)"]:::frontend
        Utils["Shared Utils & Hooks<br>(lib/)"]:::frontend
        Styles["Styles & Tailwind<br>(globals.css,<br>tailwind.config.js)"]:::frontend
        PortsConfig["Port Config<br>(ports.ini)"]:::frontend
        StartupScripts["Startup Scripts<br>(start.js/.sh/.bat,<br>postinstall.js)"]:::frontend
        E2ETests["E2E Tests<br>(autotest.js)"]:::frontend
    end

    %% Backend Zone
    subgraph "Backend" 
        direction TB
        AppFactory["Flask App Factory<br>(app.py)"]:::backend
        Controllers["Flask Controllers<br>(controllers/*.py)"]:::backend
        BusinessServices["Business Logic<br>(services/*.py)"]:::backend
        Repositories["File Repositories<br>(file_storage.py)"]:::backend
        Models["Data Models/Schemas<br>(models/*.py)"]:::backend
        UtilsBackend["Backend Utils<br>(utils/*.py)"]:::backend
        Requirements["Python Deps<br>(requirements.txt)"]:::backend
    end

    %% Persistence Layer
    FileSystem[(Local File System)]:::persistence

    %% CI/CD
    CICD["GitHub Actions<br>(ci.yml)"]:::ci

    %% Flows
    NextApp -->|renders| Views
    Views -->|uses| UIComponents
    Views -->|wraps| ErrorBoundary
    Views -->|dispatches| Stores
    Views -->|calls| ServiceHooks
    ServiceHooks -->|uses| APIService
    APIService -->|HTTP requests<br>port 5000| Controllers
    Controllers -->|delegates| BusinessServices
    BusinessServices -->|reads/writes| Repositories
    Repositories -->|persistence| FileSystem
    Controllers -->|uses| UtilsBackend
    BusinessServices -->|uses| Models
    BusinessServices -->|uses| UtilsBackend
    APIService -->|reads| PortsConfig
    StartupScripts -->|start| NextApp
    StartupScripts -->|start| AppFactory
    E2ETests -->|test| NextApp
    E2ETests -->|test| AppFactory
    CICD -->|runs| E2ETests
    CICD -->|runs| StartupScripts

    %% Click Events
    click NextApp "https://github.com/aytzey/codetopromptgenerator/blob/main/pages/_app.tsx"
    click MainPage "https://github.com/aytzey/codetopromptgenerator/blob/main/pages/index.tsx"
    click Views "https://github.com/aytzey/codetopromptgenerator/tree/main/views/"
    click UIComponents "https://github.com/aytzey/codetopromptgenerator/tree/main/components/ui/"
    click ErrorBoundary "https://github.com/aytzey/codetopromptgenerator/blob/main/components/ErrorBoundary.tsx"
    click Stores "https://github.com/aytzey/codetopromptgenerator/tree/main/stores/"
    click APIService "https://github.com/aytzey/codetopromptgenerator/blob/main/services/apiService.ts"
    click ServiceHooks "https://github.com/aytzey/codetopromptgenerator/tree/main/services/"
    click Utils "https://github.com/aytzey/codetopromptgenerator/tree/main/lib/"
    click Styles "https://github.com/aytzey/codetopromptgenerator/blob/main/styles/globals.css"
    click Styles "https://github.com/aytzey/codetopromptgenerator/blob/main/tailwind.config.js"
    click PortsConfig "https://github.com/aytzey/codetopromptgenerator/blob/main/ports.ini"
    click StartupScripts "https://github.com/aytzey/codetopromptgenerator/blob/main/start.js"
    click StartupScripts "https://github.com/aytzey/codetopromptgenerator/blob/main/start.sh"
    click StartupScripts "https://github.com/aytzey/codetopromptgenerator/blob/main/start.bat"
    click StartupScripts "https://github.com/aytzey/codetopromptgenerator/blob/main/scripts/postinstall.js"
    click E2ETests "https://github.com/aytzey/codetopromptgenerator/blob/main/scripts/autotest.js"
    click CICD "https://github.com/aytzey/codetopromptgenerator/blob/main/.github/workflows/ci.yml"
    click AppFactory "https://github.com/aytzey/codetopromptgenerator/blob/main/python_backend/app.py"
    click Controllers "https://github.com/aytzey/codetopromptgenerator/tree/main/python_backend/controllers/"
    click BusinessServices "https://github.com/aytzey/codetopromptgenerator/tree/main/python_backend/services/"
    click Repositories "https://github.com/aytzey/codetopromptgenerator/blob/main/python_backend/repositories/file_storage.py"
    click Models "https://github.com/aytzey/codetopromptgenerator/tree/main/python_backend/models/"
    click UtilsBackend "https://github.com/aytzey/codetopromptgenerator/tree/main/python_backend/utils/"
    click Requirements "https://github.com/aytzey/codetopromptgenerator/blob/main/python_backend/requirements.txt"

    %% Styles
    classDef frontend fill:#bbdefb,stroke:#1e88e5,color:#0d47a1
    classDef backend fill:#c8e6c9,stroke:#388e3c,color:#1b5e20
    classDef persistence fill:#eeeeee,stroke:#757575,color:#424242,stroke-dasharray: 5 5
    classDef ci fill:#ffe0b2,stroke:#ef6c00,color:#e65100,shape:octagon
    class NextApp,MainPage,Views,UIComponents,ErrorBoundary,Stores,APIService,ServiceHooks,Utils,Styles,PortsConfig,StartupScripts,E2ETests frontend
    class AppFactory,Controllers,BusinessServices,Repositories,Models,UtilsBackend,Requirements backend
    class FileSystem persistence
    class CICD ci
```
