# harshini-raja/ai_greeting_cards architecture

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

- Interactive diagram: https://gitdiagram.com/harshini-raja/ai_greeting_cards
- Repository: https://github.com/harshini-raja/ai_greeting_cards

## Overview

#### Purpose and Entry Points
This is a Python greeting-card generation engine, currently centered on birthday-card assets and a JSON template. The likely runnable entry point is `run_standalone.py`; `generate_placeholders.py` supports asset/template preparation. The package API begins at `card_engine/__init__.py`.

#### Application Orchestration
`card_engine/card_service.py` is the primary application-service boundary: it likely coordinates template selection, domain input, layout, and rendering into generated card output. `card_engine/domain.py` defines the core card concepts and data exchanged between stages. `run_standalone.py` is the outer execution boundary for local generation.

#### Template and Asset Inputs
Templates are separated from executable logic. `templates/birthday_classic.json` defines a birthday-card composition, while `card_engine/templates.py` loads or interprets template definitions. Static visual inputs are organized under `assets/birthday/` and `assets/birthday/base`; `card_engine/assets.py` resolves and supplies those resources to the generation pipeline.

#### Layout and Typography Stage
`card_engine/layout.py` converts template/domain content into positioned visual elements. `card_engine/typography.py` handles text-specific decisions such as font-related measurement or styling. This separation makes text placement a distinct concern from overall card composition.

#### Rendering Boundary
`card_engine/render.py` turns resolved layout and assets into the final card artifact. `card_engine/card_service.py` should be the caller-facing layer above this renderer, keeping output production separate from template parsing and domain construction. Generated artifacts are represented by the repository’s `output/` directory.

#### Primary Flow
The intended control flow is: standalone caller → card service → domain/template and asset resolution → layout/typography → renderer → `output/`. Template JSON and static assets are input boundaries; rendering is the production boundary. `generate_placeholders.py` likely creates fallback or development visual resources before normal rendering.

#### Runtime and Infrastructure
The repository is a local Python package with filesystem-based templates, assets, and output rather than visible network infrastructure or external services. No deployment, database, queue, or web-server entry point is present in the supplied tree.

Main entry points: [`card_engine/card_service.py`](https://github.com/harshini-raja/ai_greeting_cards/blob/main/card_engine/card_service.py) (Card service), [`card_engine/layout.py`](https://github.com/harshini-raja/ai_greeting_cards/blob/main/card_engine/layout.py) (Layout engine), [`card_engine/assets.py`](https://github.com/harshini-raja/ai_greeting_cards/blob/main/card_engine/assets.py) (Asset resolver), [`card_engine/render.py`](https://github.com/harshini-raja/ai_greeting_cards/blob/main/card_engine/render.py) (Renderer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry Points"]
  node_standalone["Standalone runner<br/>Python entry point<br/>[run_standalone.py]"]
  node_placeholder_generator["Placeholder generator<br/>Preparation script"]
  node_package_api["Package API<br/>Python package<br/>[__init__.py]"]
end

subgraph group_inputs["Template &amp; Assets"]
  node_template_json["Birthday classic template<br/>JSON template"]
  node_birthday_assets["Birthday assets<br/>Static assets"]
  node_base_assets["Base birthday assets<br/>Static assets"]
end

subgraph group_engine["Card Engine"]
  node_card_service["Card service<br/>Application service<br/>[card_service.py]"]
  node_domain["Card domain<br/>Domain model<br/>[domain.py]"]
  node_template_loader["Template loader<br/>Template interpreter<br/>[templates.py]"]
  node_asset_resolver["Asset resolver<br/>Asset provider<br/>[assets.py]"]
  node_layout["Layout engine<br/>Composition stage<br/>[layout.py]"]
  node_typography["Typography engine<br/>Text layout stage<br/>[typography.py]"]
  node_renderer["Renderer<br/>Rendering boundary<br/>[render.py]"]
end

subgraph group_output["Generated Output"]
  node_generated_output["Output artifacts<br/>Filesystem output"]
end

node_standalone -->|"generates card"| node_card_service
node_package_api -->|"exposes"| node_card_service
node_placeholder_generator -.->|"prepares"| node_birthday_assets
node_card_service -->|"builds input"| node_domain
node_card_service -->|"selects template"| node_template_loader
node_card_service -->|"resolves assets"| node_asset_resolver
node_card_service -->|"composes card"| node_layout
node_template_json -->|"template definition"| node_template_loader
node_birthday_assets -->|"visual resources"| node_asset_resolver
node_base_assets -->|"base resources"| node_asset_resolver
node_domain -->|"card content"| node_layout
node_template_loader -->|"composition rules"| node_layout
node_asset_resolver -->|"resolved resources"| node_layout
node_layout -->|"text placement"| node_typography
node_typography -->|"styled text"| node_renderer
node_layout -->|"positioned elements"| node_renderer
node_asset_resolver -->|"renderable assets"| node_renderer
node_renderer -->|"writes card"| node_generated_output

click node_standalone "https://github.com/harshini-raja/ai_greeting_cards/blob/main/run_standalone.py"
click node_placeholder_generator "https://github.com/harshini-raja/ai_greeting_cards/blob/main/generate_placeholders.py"
click node_package_api "https://github.com/harshini-raja/ai_greeting_cards/blob/main/card_engine/__init__.py"
click node_card_service "https://github.com/harshini-raja/ai_greeting_cards/blob/main/card_engine/card_service.py"
click node_domain "https://github.com/harshini-raja/ai_greeting_cards/blob/main/card_engine/domain.py"
click node_template_json "https://github.com/harshini-raja/ai_greeting_cards/blob/main/templates/birthday_classic.json"
click node_template_loader "https://github.com/harshini-raja/ai_greeting_cards/blob/main/card_engine/templates.py"
click node_base_assets "https://github.com/harshini-raja/ai_greeting_cards/tree/main/assets/birthday/base"
click node_asset_resolver "https://github.com/harshini-raja/ai_greeting_cards/blob/main/card_engine/assets.py"
click node_layout "https://github.com/harshini-raja/ai_greeting_cards/blob/main/card_engine/layout.py"
click node_typography "https://github.com/harshini-raja/ai_greeting_cards/blob/main/card_engine/typography.py"
click node_renderer "https://github.com/harshini-raja/ai_greeting_cards/blob/main/card_engine/render.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_standalone,node_placeholder_generator,node_package_api toneBlue
class node_template_json,node_birthday_assets,node_base_assets toneAmber
class node_card_service,node_domain,node_template_loader,node_asset_resolver,node_layout,node_typography,node_renderer toneMint
class node_generated_output toneRose
```

## Components

### Entry Points

- [Standalone runner](https://github.com/harshini-raja/ai_greeting_cards/blob/main/run_standalone.py): Python entry point · Local card-generation execution boundary. · `run_standalone.py`
- [Placeholder generator](https://github.com/harshini-raja/ai_greeting_cards/blob/main/generate_placeholders.py): Preparation script · Prepares fallback or development visual resources. · `generate_placeholders.py`
- [Package API](https://github.com/harshini-raja/ai_greeting_cards/blob/main/card_engine/__init__.py): Python package · `card_engine/__init__.py`

### Template & Assets

- [Birthday classic template](https://github.com/harshini-raja/ai_greeting_cards/blob/main/templates/birthday_classic.json): JSON template · Defines the birthday-card composition. · `templates/birthday_classic.json`
- **Birthday assets**: Static assets
- [Base birthday assets](https://github.com/harshini-raja/ai_greeting_cards/tree/main/assets/birthday/base): Static assets · `assets/birthday/base`

### Card Engine

- [Card service](https://github.com/harshini-raja/ai_greeting_cards/blob/main/card_engine/card_service.py): Application service · Coordinates the card generation pipeline. · `card_engine/card_service.py`
- [Card domain](https://github.com/harshini-raja/ai_greeting_cards/blob/main/card_engine/domain.py): Domain model · Core card concepts exchanged between stages. · `card_engine/domain.py`
- [Template loader](https://github.com/harshini-raja/ai_greeting_cards/blob/main/card_engine/templates.py): Template interpreter · `card_engine/templates.py`
- [Asset resolver](https://github.com/harshini-raja/ai_greeting_cards/blob/main/card_engine/assets.py): Asset provider · `card_engine/assets.py`
- [Layout engine](https://github.com/harshini-raja/ai_greeting_cards/blob/main/card_engine/layout.py): Composition stage · Positions resolved visual elements. · `card_engine/layout.py`
- [Typography engine](https://github.com/harshini-raja/ai_greeting_cards/blob/main/card_engine/typography.py): Text layout stage · Measures and styles text for placement. · `card_engine/typography.py`
- [Renderer](https://github.com/harshini-raja/ai_greeting_cards/blob/main/card_engine/render.py): Rendering boundary · Produces the final card artifact. · `card_engine/render.py`

### Generated Output

- **Output artifacts**: Filesystem output

## Connections

- Standalone runner → Card service: generates card
- Package API → Card service: exposes
- Placeholder generator → Birthday assets: prepares
- Card service → Card domain: builds input
- Card service → Template loader: selects template
- Card service → Asset resolver: resolves assets
- Card service → Layout engine: composes card
- Birthday classic template → Template loader: template definition
- Birthday assets → Asset resolver: visual resources
- Base birthday assets → Asset resolver: base resources
- Card domain → Layout engine: card content
- Template loader → Layout engine: composition rules
- Asset resolver → Layout engine: resolved resources
- Layout engine → Typography engine: text placement
- Typography engine → Renderer: styled text
- Layout engine → Renderer: positioned elements
- Asset resolver → Renderer: renderable assets
- Renderer → Output artifacts: writes card