# dilip-sheesh/creativerse-rocketium architecture

> Architecture diagram of the GitHub repository dilip-sheesh/creativerse-rocketium, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dilip-sheesh/creativerse-rocketium
- Repository: https://github.com/dilip-sheesh/creativerse-rocketium

## Overview

1. **Overall shape**
   - This repository is a **server-rendered Flask application** for automated ad compliance review.
   - The core architecture is a simple pipeline: **web upload → image analysis → LLM-based policy review → HTML result page**.

2. **Entry point and app boundary**
   - `run.py` is the runtime entrypoint.
   - The actual Flask app lives under `app/`, which separates configuration, route handlers, services, templates, and static assets.
   - There is also a top-level `routes.py`, but the main application structure is clearly organized in `app/routes/*`.

3. **UI / presentation layer**
   - The frontend is built with **server-side HTML templates** in `app/templates/`.
   - There are two main user flows reflected in the templates:
     - `company/*` for company/brand-guideline review
     - `design/*` for design/project review
   - `app/static/styles.css` provides styling, and uploaded images are stored under `app/static/uploads/`.

4. **Route organization**
   - `app/routes/main.py` likely handles the landing page and shared navigation.
   - `app/routes/company.py` and `app/routes/design.py` split the application into two domain-specific workflows.
   - The route layer is the orchestration boundary: it receives uploads, calls services, and renders results.

5. **Review pipeline**
   - The app’s main data flow starts when a user uploads an ad creative through one of the review forms.
   - The uploaded image is processed by an AWS vision step first, then passed into an LLM review step.
   - The output is a structured compliance report containing a **score**, **violations**, and a **safe / not safe** verdict.

6. **Computer vision / OCR subsystem**
   - `app/services/rekognition_service.py` encapsulates **AWS Rekognition** usage.
   - This service is responsible for extracting image content such as **text**, **labels**, and likely object-level cues from the ad creative.
   - This layer is the vision boundary between raw image input and language-model reasoning.

7. **LLM review subsystem**
   - `app/services/bedrock_services.py` encapsulates **AWS Bedrock** integration.
   - The readme says it uses **Meta Llama 3** to evaluate the ad against brand and platform rules.
   - This service is where extracted visual/textual evidence plus guideline text are turned into a structured compliance decision.

8. **Guidelines and policy data**
   - `app/static/guidelines/ad_guidelines.csv` is a local policy artifact used as the review reference.
   - The app appears to combine **brand guidance** and **platform rules** such as Facebook/Google/Instagram-style constraints.
   - This CSV is an important domain input, not just static content.

9. **Domain-specific templates and outputs**
   - The `company` templates include pages like `requirements_display`, `submission_details`, `review`, and `result`, suggesting a workflow focused on submitting and evaluating company requirements.
   - The `design` templates include `ongoing_projects`, `upload`, `review`, and `result`, suggesting a workflow for design teams to submit creatives and track review status.
   - Both flows converge on the same core review engine, but present different UX around it.

10. **State and storage**
   - The repo does **not** show a database layer.
   - State appears to be mostly local and file-based: uploaded files, guideline CSVs, and rendered results.
   - That means the architecture is lightweight and likely stateless across requests aside from filesystem artifacts.

11. **External dependencies**
   - The two material external services are:
     - **AWS Rekognition** for image text/label extraction
     - **AWS Bedrock** for compliance reasoning and structured feedback
   - `boto3` is the AWS SDK glue between the Flask app and those services.
   - `Pillow` is present for image handling.

12. **What to draw in an architecture diagram**
   - Draw three layers: **Flask routes/UI**, **service layer**, and **AWS dependencies**.
   - Show the image upload entering the Flask route layer, flowing into Rekognition, then Bedrock, then back to rendered HTML results.
   - Include the guideline CSV as a local policy input feeding the review logic.
   - Treat `company` and `design` as two front-door workflows sharing the same backend review pipeline.

Main entry points: [`AdReview/app/routes/company.py`](https://github.com/dilip-sheesh/creativerse-rocketium/blob/main/AdReview/app/routes/company.py) (company routes), [`AdReview/app/routes/design.py`](https://github.com/dilip-sheesh/creativerse-rocketium/blob/main/AdReview/app/routes/design.py) (design routes), [`AdReview/app/__init__.py`](https://github.com/dilip-sheesh/creativerse-rocketium/blob/main/AdReview/app/__init__.py) (app), [`AdReview/app/routes/main.py`](https://github.com/dilip-sheesh/creativerse-rocketium/blob/main/AdReview/app/routes/main.py) (main routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_run_py["run.py<br/>entrypoint<br/>[run.py]"]
end

subgraph group_app_core["App Core"]
  node_app_init["app<br/>flask package<br/>[__init__.py]"]
  node_app_config["config<br/>settings<br/>[config.py]"]
  node_legacy_routes["routes.py<br/>route shim<br/>[routes.py]"]
  node_main_route["main routes<br/>landing routes<br/>[main.py]"]
  node_company_route["company routes<br/>company workflow<br/>[company.py]"]
  node_design_route["design routes<br/>design workflow<br/>[design.py]"]
  node_rekognition_service["Rekognition<br/>vision service"]
  node_bedrock_service["Bedrock<br/>llm service"]
end

subgraph group_ui_company["Company UI"]
  node_company_index["company home<br/>template<br/>[index.html]"]
  node_company_requirements["requirements<br/>template"]
  node_company_submission["submission<br/>template"]
  node_company_review["company review<br/>template<br/>[review.html]"]
  node_company_result["company result<br/>template<br/>[result.html]"]
end

subgraph group_ui_design["Design UI"]
  node_design_index["design home<br/>template<br/>[index.html]"]
  node_design_projects["projects<br/>template"]
  node_design_upload["upload<br/>template<br/>[upload.html]"]
  node_design_review["design review<br/>template<br/>[review.html]"]
  node_design_result["design result<br/>template<br/>[result.html]"]
end

subgraph group_assets["Assets"]
  node_guidelines_csv["guidelines CSV<br/>policy data<br/>[ad_guidelines.csv]"]
  node_styles_css["styles.css<br/>stylesheet<br/>[styles.css]"]
  node_uploads_dir[("uploads<br/>file storage")]
end

subgraph group_external["AWS Services"]
  node_aws_rekognition(("AWS Rekognition<br/>external vision API"))
  node_aws_bedrock(("AWS Bedrock<br/>external llm API"))
end

node_run_py -->|"boot app"| node_app_init
node_app_init -->|"loads config"| node_app_config
node_app_init -->|"registers"| node_main_route
node_app_init -->|"registers"| node_company_route
node_app_init -->|"registers"| node_design_route
node_legacy_routes -.->|"dispatches"| node_main_route
node_main_route -->|"renders"| node_company_index
node_main_route -->|"renders"| node_design_index
node_company_route -->|"renders"| node_company_requirements
node_company_route -->|"renders"| node_company_submission
node_company_route -->|"renders"| node_company_review
node_company_route -->|"renders"| node_company_result
node_design_route -->|"renders"| node_design_projects
node_design_route -->|"renders"| node_design_upload
node_design_route -->|"renders"| node_design_review
node_design_route -->|"renders"| node_design_result
node_company_route -->|"reads/writes"| node_uploads_dir
node_design_route -->|"reads/writes"| node_uploads_dir
node_company_route -->|"uses policy"| node_guidelines_csv
node_design_route -->|"uses policy"| node_guidelines_csv
node_company_route -->|"analyzes image"| node_rekognition_service
node_design_route -->|"analyzes image"| node_rekognition_service
node_rekognition_service -->|"calls"| node_aws_rekognition
node_company_route -->|"reviews"| node_bedrock_service
node_design_route -->|"reviews"| node_bedrock_service
node_bedrock_service -->|"calls"| node_aws_bedrock
node_company_route -.->|"styles"| node_styles_css
node_design_route -.->|"styles"| node_styles_css

click node_run_py "https://github.com/dilip-sheesh/creativerse-rocketium/blob/main/AdReview/run.py"
click node_app_init "https://github.com/dilip-sheesh/creativerse-rocketium/blob/main/AdReview/app/__init__.py"
click node_app_config "https://github.com/dilip-sheesh/creativerse-rocketium/blob/main/AdReview/app/config.py"
click node_legacy_routes "https://github.com/dilip-sheesh/creativerse-rocketium/blob/main/AdReview/routes.py"
click node_main_route "https://github.com/dilip-sheesh/creativerse-rocketium/blob/main/AdReview/app/routes/main.py"
click node_company_route "https://github.com/dilip-sheesh/creativerse-rocketium/blob/main/AdReview/app/routes/company.py"
click node_design_route "https://github.com/dilip-sheesh/creativerse-rocketium/blob/main/AdReview/app/routes/design.py"
click node_rekognition_service "https://github.com/dilip-sheesh/creativerse-rocketium/blob/main/AdReview/app/services/rekognition_service.py"
click node_bedrock_service "https://github.com/dilip-sheesh/creativerse-rocketium/blob/main/AdReview/app/services/bedrock_services.py"
click node_guidelines_csv "https://github.com/dilip-sheesh/creativerse-rocketium/blob/main/AdReview/app/static/guidelines/ad_guidelines.csv"
click node_styles_css "https://github.com/dilip-sheesh/creativerse-rocketium/blob/main/AdReview/app/static/styles.css"
click node_uploads_dir "https://github.com/dilip-sheesh/creativerse-rocketium/tree/main/AdReview/app/static/uploads"
click node_company_index "https://github.com/dilip-sheesh/creativerse-rocketium/blob/main/AdReview/app/templates/company/index.html"
click node_company_requirements "https://github.com/dilip-sheesh/creativerse-rocketium/blob/main/AdReview/app/templates/company/requirements_display.html"
click node_company_submission "https://github.com/dilip-sheesh/creativerse-rocketium/blob/main/AdReview/app/templates/company/submission_details.html"
click node_company_review "https://github.com/dilip-sheesh/creativerse-rocketium/blob/main/AdReview/app/templates/company/review.html"
click node_company_result "https://github.com/dilip-sheesh/creativerse-rocketium/blob/main/AdReview/app/templates/company/result.html"
click node_design_index "https://github.com/dilip-sheesh/creativerse-rocketium/blob/main/AdReview/app/templates/design/index.html"
click node_design_projects "https://github.com/dilip-sheesh/creativerse-rocketium/blob/main/AdReview/app/templates/design/ongoing_projects.html"
click node_design_upload "https://github.com/dilip-sheesh/creativerse-rocketium/blob/main/AdReview/app/templates/design/upload.html"
click node_design_review "https://github.com/dilip-sheesh/creativerse-rocketium/blob/main/AdReview/app/templates/design/review.html"
click node_design_result "https://github.com/dilip-sheesh/creativerse-rocketium/blob/main/AdReview/app/templates/design/result.html"

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_run_py toneBlue
class node_app_init,node_app_config,node_legacy_routes,node_main_route,node_company_route,node_design_route,node_rekognition_service,node_bedrock_service toneAmber
class node_company_index,node_company_requirements,node_company_submission,node_company_review,node_company_result toneMint
class node_design_index,node_design_projects,node_design_upload,node_design_review,node_design_result toneRose
class node_guidelines_csv,node_styles_css,node_uploads_dir toneIndigo
class node_aws_rekognition,node_aws_bedrock toneTeal
```

## Components

### Runtime

Process entry and Flask app bootstrap

- [run.py](https://github.com/dilip-sheesh/creativerse-rocketium/blob/main/AdReview/run.py): entrypoint · Starts the Flask application · `AdReview/run.py`

### App Core

Flask package, routing, and services

- [app](https://github.com/dilip-sheesh/creativerse-rocketium/blob/main/AdReview/app/__init__.py): flask package · Application package boundary and setup · `AdReview/app/__init__.py`
- [config](https://github.com/dilip-sheesh/creativerse-rocketium/blob/main/AdReview/app/config.py): settings · Runtime configuration and environment settings · `AdReview/app/config.py`
- [routes.py](https://github.com/dilip-sheesh/creativerse-rocketium/blob/main/AdReview/routes.py): route shim · Top-level routing module / compatibility boundary · `AdReview/routes.py`
- [main routes](https://github.com/dilip-sheesh/creativerse-rocketium/blob/main/AdReview/app/routes/main.py): landing routes · Shared landing page and navigation · `AdReview/app/routes/main.py`
- [company routes](https://github.com/dilip-sheesh/creativerse-rocketium/blob/main/AdReview/app/routes/company.py): company workflow · Brand-guideline submission and review flow · `AdReview/app/routes/company.py`
- [design routes](https://github.com/dilip-sheesh/creativerse-rocketium/blob/main/AdReview/app/routes/design.py): design workflow · Creative upload and project review flow · `AdReview/app/routes/design.py`
- [Rekognition](https://github.com/dilip-sheesh/creativerse-rocketium/blob/main/AdReview/app/services/rekognition_service.py): vision service · Extracts text and labels from uploaded creatives · `AdReview/app/services/rekognition_service.py`
- [Bedrock](https://github.com/dilip-sheesh/creativerse-rocketium/blob/main/AdReview/app/services/bedrock_services.py): llm service · Runs policy reasoning and structured compliance review · `AdReview/app/services/bedrock_services.py`

### Company UI

Company/brand-guideline review screens

- [company home](https://github.com/dilip-sheesh/creativerse-rocketium/blob/main/AdReview/app/templates/company/index.html): template · Company workflow landing page · `AdReview/app/templates/company/index.html`
- [requirements](https://github.com/dilip-sheesh/creativerse-rocketium/blob/main/AdReview/app/templates/company/requirements_display.html): template · Displays company requirements and guidelines · `AdReview/app/templates/company/requirements_display.html`
- [submission](https://github.com/dilip-sheesh/creativerse-rocketium/blob/main/AdReview/app/templates/company/submission_details.html): template · Shows submission details before review · `AdReview/app/templates/company/submission_details.html`
- [company review](https://github.com/dilip-sheesh/creativerse-rocketium/blob/main/AdReview/app/templates/company/review.html): template · Company review form and evidence summary · `AdReview/app/templates/company/review.html`
- [company result](https://github.com/dilip-sheesh/creativerse-rocketium/blob/main/AdReview/app/templates/company/result.html): template · Final compliance result page · `AdReview/app/templates/company/result.html`

### Design UI

Design/project review screens

- [design home](https://github.com/dilip-sheesh/creativerse-rocketium/blob/main/AdReview/app/templates/design/index.html): template · Design workflow landing page · `AdReview/app/templates/design/index.html`
- [projects](https://github.com/dilip-sheesh/creativerse-rocketium/blob/main/AdReview/app/templates/design/ongoing_projects.html): template · Lists ongoing design projects · `AdReview/app/templates/design/ongoing_projects.html`
- [upload](https://github.com/dilip-sheesh/creativerse-rocketium/blob/main/AdReview/app/templates/design/upload.html): template · Creative upload form · `AdReview/app/templates/design/upload.html`
- [design review](https://github.com/dilip-sheesh/creativerse-rocketium/blob/main/AdReview/app/templates/design/review.html): template · Design review form and evidence summary · `AdReview/app/templates/design/review.html`
- [design result](https://github.com/dilip-sheesh/creativerse-rocketium/blob/main/AdReview/app/templates/design/result.html): template · Final review outcome page · `AdReview/app/templates/design/result.html`

### Assets

Static files, uploads, and policy data

- [guidelines CSV](https://github.com/dilip-sheesh/creativerse-rocketium/blob/main/AdReview/app/static/guidelines/ad_guidelines.csv): policy data · Local ad rules and brand guidance reference · `AdReview/app/static/guidelines/ad_guidelines.csv`
- [styles.css](https://github.com/dilip-sheesh/creativerse-rocketium/blob/main/AdReview/app/static/styles.css): stylesheet · Shared server-rendered UI styling · `AdReview/app/static/styles.css`
- [uploads](https://github.com/dilip-sheesh/creativerse-rocketium/tree/main/AdReview/app/static/uploads): file storage · Persisted uploaded ad creatives · `AdReview/app/static/uploads`

### AWS Services

Managed vision and LLM dependencies

- **AWS Rekognition**: external vision API · Managed image analysis service
- **AWS Bedrock**: external llm API · Managed LLM reasoning service

## Connections

- run.py → app: boot app · Launches the Flask package
- app → config: loads config · Initializes app settings
- app → main routes: registers · Attaches shared routes
- app → company routes: registers · Attaches company workflow routes
- app → design routes: registers · Attaches design workflow routes
- routes.py → main routes: dispatches · Top-level route boundary forwards to app routes
- main routes → company home: renders · Shows company entry page
- main routes → design home: renders · Shows design entry page
- company routes → requirements: renders · Displays policy/requirements context
- company routes → submission: renders · Shows submission details
- company routes → company review: renders · Presents company review UI
- company routes → company result: renders · Displays final compliance result
- design routes → projects: renders · Shows project list
- design routes → upload: renders · Presents upload form
- design routes → design review: renders · Presents design review UI
- design routes → design result: renders · Displays final outcome
- company routes → uploads: reads/writes · Stores uploaded creatives and artifacts
- design routes → uploads: reads/writes · Stores uploaded creatives and artifacts
- company routes → guidelines CSV: uses policy · Loads local review criteria
- design routes → guidelines CSV: uses policy · Loads local review criteria
- company routes → Rekognition: analyzes image · Extracts visual evidence from uploads
- design routes → Rekognition: analyzes image · Extracts visual evidence from uploads
- Rekognition → AWS Rekognition: calls · Delegates image analysis to AWS
- company routes → Bedrock: reviews · Generates compliance decision
- design routes → Bedrock: reviews · Generates compliance decision
- Bedrock → AWS Bedrock: calls · Delegates reasoning to AWS LLM service
- company routes → styles.css: styles · Shared page styling
- design routes → styles.css: styles · Shared page styling
