# pbaniket/chimeragrid architecture

> Architecture diagram of the GitHub repository pbaniket/chimeragrid, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pbaniket/chimeragrid
- Repository: https://github.com/pbaniket/chimeragrid

## Overview

1. **Overall shape**
   ChimeraGrid is a single Python web application with a server-rendered UI. The architecture is centered on a Flask backend, HTML templates, static assets, and an AI-assisted transformation engine.

2. **Primary entrypoint**
   The repository has `appy.py` as the likely Flask application entrypoint. From the README, this is what gets run to start the service. There is no separate frontend app, worker service, or database layer in the tree.

3. **User-facing flow**
   The app appears to guide users through a multi-step wizard:
   - home / landing
   - file upload
   - column selection
   - sample display
   - target input
   - transformation review
   - results
   The templates in `templates/` map directly to these stages.

4. **Frontend boundary**
   The UI is rendered server-side with Jinja templates in `templates/`, while `static/` contains the browser-side CSS and JavaScript. `script.js` likely handles client-side interactivity for the wizard, previews, or form behavior; the styling is split across `style.css` and `home.css`.

5. **Core backend responsibility**
   The Flask layer likely orchestrates the entire workflow: receiving uploaded tabular data, storing intermediate selections in request/session state, rendering the next page, and eventually returning the generated transformation output. This backend is the main boundary between browser interaction and transformation logic.

6. **Transformation engine**
   `transformer.py` is the key non-UI module. Based on the README, it likely builds prompts for the LLM, interprets examples from the selected table column(s), and produces a Python transformation function. This module is the main separation point between web orchestration and AI/data logic.

7. **External AI dependency**
   The repository is explicitly integrated with Gemini 1.5 Flash through `google-generativeai`. That external LLM service is a core dependency, not an optional add-on: it is what turns a few examples into a human-readable Python function. The architecture therefore depends on outbound network calls to Google’s model API.

8. **Data flow through the system**
   The central data path is:
   uploaded table -> parsed into pandas/JSON-friendly structures -> user selects relevant columns and examples -> LLM prompt is assembled -> Gemini returns transformation logic -> generated Python code is shown in the review/results pages.
   The application is focused on transforming tabular data rather than training or storing models.

9. **Information passed between steps**
   The intermediate pages suggest the app preserves progressively richer context: the raw uploaded dataset, chosen source/target columns, a sample subset, the desired transformation intent, and then the generated code/output. Since there is no database directory or persistence layer, this state is likely temporary and held in-memory or session-backed across requests.

10. **Output model**
   The product emphasizes transparent, editable Python output rather than a black-box prediction. So the final architectural output is not just transformed data, but also an inspectable transformation function, which is a distinct deliverable from the UI’s result page.

11. **Technology stack that affects architecture**
   The app is Python/Flask on the server, pandas for data handling, and standard HTML/CSS/JavaScript on the client. Tailwind CSS is mentioned in the README, which suggests the UI is styled as a utility-first, template-driven interface rather than a component framework.

12. **What is not present**
   There is no evidence of a database, message queue, auth subsystem, or multi-service backend in this repository. That makes ChimeraGrid a compact, request-driven web app whose main architectural concerns are form flow, data parsing, and LLM integration.

Main entry points: [`appy.py`](https://github.com/pbaniket/chimeragrid/blob/main/appy.py) (appy.py), [`transformer.py`](https://github.com/pbaniket/chimeragrid/blob/main/transformer.py) (transformer.py), [`templates/upload.html`](https://github.com/pbaniket/chimeragrid/blob/main/templates/upload.html) (Upload), [`templates/column_selection.html`](https://github.com/pbaniket/chimeragrid/blob/main/templates/column_selection.html) (Columns)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Server UI"]
  node_home["Home<br/>landing page<br/>[home.html]"]
  node_upload["Upload<br/>file step<br/>[upload.html]"]
  node_columns["Columns<br/>selection step"]
  node_sample["Sample<br/>preview step"]
  node_target["Target<br/>intent step<br/>[target_input.html]"]
  node_review["Review<br/>confirmation step"]
  node_results["Results<br/>output page<br/>[results.html]"]
  node_script["script.js<br/>ui logic<br/>[script.js]"]
  node_style["style.css<br/>global styles<br/>[style.css]"]
  node_homecss["home.css<br/>landing styles<br/>[home.css]"]
end

subgraph group_backend["Flask App"]
  node_entrypoint["appy.py<br/>flask entrypoint<br/>[appy.py]"]
  node_pandas[("Tabular Data<br/>data handling")]
  node_session["Request State<br/>workflow state"]
end

subgraph group_ai["Transformation Engine"]
  node_transformer["transformer.py<br/>llm workflow<br/>[transformer.py]"]
  node_gemini(("Gemini API<br/>external llm"))
end

node_entrypoint -->|"serves"| node_home
node_entrypoint -->|"routes"| node_upload
node_entrypoint -->|"routes"| node_columns
node_entrypoint -->|"routes"| node_sample
node_entrypoint -->|"routes"| node_target
node_entrypoint -->|"routes"| node_review
node_entrypoint -->|"routes"| node_results
node_upload -->|"parses"| node_pandas
node_columns -->|"stores"| node_session
node_sample -->|"stores"| node_session
node_target -->|"stores"| node_session
node_entrypoint -->|"calls"| node_transformer
node_transformer -->|"consumes"| node_pandas
node_transformer -->|"prompts"| node_gemini
node_gemini -->|"returns"| node_transformer
node_transformer -->|"produces"| node_review
node_review -->|"confirms"| node_results
node_script -.->|"enhances"| node_upload
node_script -.->|"enhances"| node_columns
node_style -.->|"styles"| node_home
node_homecss -.->|"styles"| node_home

click node_entrypoint "https://github.com/pbaniket/chimeragrid/blob/main/appy.py"
click node_home "https://github.com/pbaniket/chimeragrid/blob/main/templates/home.html"
click node_upload "https://github.com/pbaniket/chimeragrid/blob/main/templates/upload.html"
click node_columns "https://github.com/pbaniket/chimeragrid/blob/main/templates/column_selection.html"
click node_sample "https://github.com/pbaniket/chimeragrid/blob/main/templates/sample_display.html"
click node_target "https://github.com/pbaniket/chimeragrid/blob/main/templates/target_input.html"
click node_review "https://github.com/pbaniket/chimeragrid/blob/main/templates/review_transformation.html"
click node_results "https://github.com/pbaniket/chimeragrid/blob/main/templates/results.html"
click node_script "https://github.com/pbaniket/chimeragrid/blob/main/static/script.js"
click node_style "https://github.com/pbaniket/chimeragrid/blob/main/static/style.css"
click node_homecss "https://github.com/pbaniket/chimeragrid/blob/main/static/home.css"
click node_transformer "https://github.com/pbaniket/chimeragrid/blob/main/transformer.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_home,node_upload,node_columns,node_sample,node_target,node_review,node_results,node_script,node_style,node_homecss toneBlue
class node_entrypoint,node_pandas,node_session toneAmber
class node_transformer,node_gemini toneMint
```

## Components

### Server UI

Server-rendered pages and browser assets for the wizard flow.

- [Home](https://github.com/pbaniket/chimeragrid/blob/main/templates/home.html): landing page · Initial landing page for the app. · `templates/home.html`
- [Upload](https://github.com/pbaniket/chimeragrid/blob/main/templates/upload.html): file step · Page for uploading the input table. · `templates/upload.html`
- [Columns](https://github.com/pbaniket/chimeragrid/blob/main/templates/column_selection.html): selection step · Page for choosing relevant columns. · `templates/column_selection.html`
- [Sample](https://github.com/pbaniket/chimeragrid/blob/main/templates/sample_display.html): preview step · Page showing sampled rows or examples. · `templates/sample_display.html`
- [Target](https://github.com/pbaniket/chimeragrid/blob/main/templates/target_input.html): intent step · Page for describing the desired transformation target. · `templates/target_input.html`
- [Review](https://github.com/pbaniket/chimeragrid/blob/main/templates/review_transformation.html): confirmation step · Page for reviewing the generated transformation. · `templates/review_transformation.html`
- [Results](https://github.com/pbaniket/chimeragrid/blob/main/templates/results.html): output page · Final page showing the generated code or output. · `templates/results.html`
- [script.js](https://github.com/pbaniket/chimeragrid/blob/main/static/script.js): ui logic · Client-side behavior for the wizard flow. · `static/script.js`
- [style.css](https://github.com/pbaniket/chimeragrid/blob/main/static/style.css): global styles · Main styling for the application UI. · `static/style.css`
- [home.css](https://github.com/pbaniket/chimeragrid/blob/main/static/home.css): landing styles · Styling for the landing page. · `static/home.css`

### Flask App

Request handling and workflow orchestration.

- [appy.py](https://github.com/pbaniket/chimeragrid/blob/main/appy.py): flask entrypoint · Starts the web app and wires routes. · `appy.py`
- **Tabular Data**: data handling · In-memory parsing and preparation of uploaded tables.
- **Request State**: workflow state · Temporary state passed between wizard steps.

### Transformation Engine

Prompting and code generation logic backed by Gemini.

- [transformer.py](https://github.com/pbaniket/chimeragrid/blob/main/transformer.py): llm workflow · Builds prompts and produces the transformation logic. · `transformer.py`
- **Gemini API**: external llm · External model service used to generate transformations.

## Connections

- appy.py → Home: serves · Renders the landing page.
- appy.py → Upload: routes · Starts the upload flow.
- appy.py → Columns: routes · Advances to column selection.
- appy.py → Sample: routes · Shows sampled data for review.
- appy.py → Target: routes · Collects the target transformation intent.
- appy.py → Review: routes · Shows the generated transformation for approval.
- appy.py → Results: routes · Displays the final output.
- Upload → Tabular Data: parses · Uploaded files are read into tabular structures.
- Columns → Request State: stores · Selected columns are kept for later steps.
- Sample → Request State: stores · Sample context is preserved across requests.
- Target → Request State: stores · User intent is carried into generation.
- appy.py → transformer.py: calls · Backend invokes the transformation engine.
- transformer.py → Tabular Data: consumes · Uses table data and examples to build context.
- transformer.py → Gemini API: prompts · Sends prompt and examples to the LLM service.
- Gemini API → transformer.py: returns · Returns generated transformation text or code.
- transformer.py → Review: produces · Feeds review page with generated function details.
- Review → Results: confirms · Approved transformation is shown as final output.
- script.js → Upload: enhances · Adds browser-side interactivity to form flow.
- script.js → Columns: enhances · Supports dynamic selection behavior.
- style.css → Home: styles · Applies the main UI theme.
- home.css → Home: styles · Applies landing-page specific styling.
