# rxz33/rayeva-ai-assignment architecture

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

- Interactive diagram: https://gitdiagram.com/rxz33/rayeva-ai-assignment
- Repository: https://github.com/rxz33/rayeva-ai-assignment

## Overview

##### What this project is (type + purpose)
This is a **Python FastAPI backend service** that exposes **two AI-powered HTTP APIs** for an ecommerce sustainability platform:

- **Module 1 (Product Categorization)**: Classify a product into sustainability categories + generate SEO tags.
- **Module 2 (B2B Proposal Generator)**: Generate a sustainable product mix + budget allocation + impact summary for a corporate client.

Architecturally, it’s a **modular monolith** with a clean separation of concerns:
- **Routes (API layer)** → **Services (prompting + AI calls + business logic)** → **Validators (AI output conformance)** → **Schemas (Pydantic request/response contracts)**, plus **Utilities (logging)**.
It also integrates with an **external LLM provider (Groq / LLM API)**.

- FastAPI service boundaries
- request/response flow per endpoint
- interaction with external LLM
- validation + logging paths
- configuration via environment variables

##### How the repo structure maps to architecture (what to put
Use the file tree to identify components:

##### Entry point / application container
- `app/main.py`

##### API layer (controllers)
- `app/routes/category.py` → endpoint: `POST /generate-category`
- `app/routes/proposal.py` → endpoint: `POST /generate-proposal`

##### Data contracts (schemas)
- `app/schemas/category_schema.py`
- `app/schemas/proposal_schema.py`

##### Service layer (core logic + AI integration)
- `app/services/ai_client.py` (the abstraction over Groq/LLM API)
- `app/services/category_service.py`
- `app/services/proposal_service.py`

- prompt construction
- calling AI client
- passing results to validators
- returning structured output

##### Validation layer
- `app/validators/category_validator.py`
- `app/validators/proposal_validator.py`

##### Observability / logging
- `app/utils/logger.py`
Logs prompts and responses to `ai_logs.json` (per README). This is an important side-effect path; show it explicitly as a data sink (file).

##### Configuration / secrets
- `.env.example` and real `.env` loaded (README says python-dotenv)
**Environment Variables** feeding into the AI client configuration (e.g., `GROQ_API_KEY`).

##### Tooling / deployment context (secondary but useful)
- `requirements.txt`, `pyproject.toml` (dependencies/build)
- `.github/workflows/lint.yml`, `.pre-commit-config.yaml` (CI quality gates)

##### Route returns `CategoryResponse`

Alternate paths (error branches) because README emphasizes error handling:
- AI call failure → return 5xx/structured error
- Invalid JSON → validator failure → return 422/400 (whatever implemented)
- Missing fields/business rule violation → validator failure

##### How to “separate into as many components as possible” without overthinking
Optionally:

##### Project-specific architectural patterns to highlight explicitly
- **Layering**: Routes → Services → Validators
- **Externalized AI integration**: AI access isolated in `ai_client.py`
- **Contract-first outputs**: Pydantic schemas + explicit validation of AI JSON
- **Observability**: prompt/response logging via `logger.py` to `ai_logs.json`
- **Environment-based secret management**: `GROQ_API_KEY` via `.env`

These are the “essential architectural elements” for this repo.

- Two distinct API modules/endpoints are visible.
- Each endpoint shows:
- schema in/out
- service called
- validator used
- AI client called
- log write performed
- Groq/LLM API is shown as an external system, not an internal module.
- `.env` / `GROQ_API_KEY` is shown feeding into AI client.
- Error/validation failure paths are included (at least at a high level).

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Diagram A — Context (C4 L1)
  %% =========================
  subgraph "Diagram A — Context (C4 Level 1)"
    direction TB

    Client["Client (API Consumer / Swagger UI)"]:::external

    subgraph "FastAPI Backend Service"
      direction TB
      App["FastAPI App Bootstrap (ASGI)"]:::container
    end

    Groq["External LLM Provider (Groq / LLM API)"]:::external
    Env["Environment Variables / Secrets (.env, GROQ_API_KEY)"]:::config
    LogSink[("ai_logs.json (Prompt/Response Logs)")]:::storage

    Client -->|"HTTPS:POST /generate-category,POST /generate-proposal"| App
    App -->|"HTTPS:LLM completion request"| Groq
    App -.->|"write logs"| LogSink
    Env -->|"configures"| App
  end

  %% =========================
  %% Diagram B — Components (C4 L2/3)
  %% =========================
  subgraph "Diagram B — FastAPI Container/Component View (C4 Level 2/3)"
    direction TB

    subgraph "Runtime: FastAPI App (app/main.py)"
      direction TB

      subgraph "API Layer (Routes)"
        direction TB
        RouteCategory["Route: POST /generate-category"]:::route
        RouteProposal["Route: POST /generate-proposal"]:::route
      end

      subgraph "Contracts (Pydantic Schemas)"
        direction TB
        CatSchemas["Category Schemas (Request/Response)"]:::schema
        PropSchemas["Proposal Schemas (Request/Response)"]:::schema
      end

      subgraph "Service Layer (Business Logic + Prompting)"
        direction TB
        CategorySvc["Service: CategoryService"]:::service
        ProposalSvc["Service: ProposalService"]:::service
        AIClient["Service: AI Client (Groq wrapper)"]:::service
      end

      subgraph "Validation Layer (AI Output Conformance)"
        direction TB
        CatValidator["Validator: Category Output"]:::validator
        PropValidator["Validator: Proposal Output"]:::validator
      end

      subgraph "Observability"
        direction TB
        Logger["Utility: Prompt/Response Logger"]:::util
        LogFile[("ai_logs.json")]:::storage
      end

      subgraph "Configuration"
        direction TB
        DotEnv["Secrets: .env / template .env.example"]:::config
      end
    end

    Groq2["External: Groq / LLM API"]:::external

    %% Route -> schema/service
    RouteCategory -->|"parse/serialize"| CatSchemas
    RouteCategory -->|"calls"| CategorySvc

    RouteProposal -->|"parse/serialize"| PropSchemas
    RouteProposal -->|"calls"| ProposalSvc

    %% Service -> AI client, validator, logger
    CategorySvc -->|"builds prompt"| AIClient
    CategorySvc -->|"validates LLM JSON"| CatValidator
    CategorySvc -.->|"logs prompt+response"| Logger

    ProposalSvc -->|"builds prompt"| AIClient
    ProposalSvc -->|"validates LLM JSON"| PropValidator
    ProposalSvc -.->|"logs prompt+response"| Logger

    %% AI Client -> config, external, logger
    DotEnv -->|"provides GROQ_API_KEY"| AIClient
    AIClient -->|"HTTPS completion"| Groq2
    AIClient -.->|"logs request/response"| Logger

    %% Logger -> file
    Logger -.->|"append/write"| LogFile
  end

  %% =========================
  %% Diagram C — Sequences (per endpoint)
  %% =========================
  subgraph "Diagram C — Runtime Sequences (per endpoint)"
    direction TB

    subgraph "Sequence 1: POST /generate-category"
      direction TB
      S1Client["Client"]:::external
      S1Route["Route: /generate-category"]:::route
      S1Schema["Schema: CategoryRequest/CategoryResponse"]:::schema
      S1Svc["CategoryService.generate_category()"]:::service
      S1AI["AIClient.complete(prompt)"]:::service
      S1Env["Env: GROQ_API_KEY"]:::config
      S1Groq["Groq LLM API"]:::external
      S1Val["CategoryValidator.validate(json)"]:::validator
      S1Log["Logger.log(prompt,response)"]:::util
      S1File[("ai_logs.json")]:::storage
      S1Err["Error Handling (HTTP 4xx/5xx)"]:::error

      S1Client -->|"request JSON"| S1Route
      S1Route -->|"parse"| S1Schema
      S1Route -->|"call"| S1Svc
      S1Svc -->|"prompt string"| S1AI
      S1Env -->|"configure"| S1AI
      S1AI -->|"HTTPS"| S1Groq
      S1Groq -->|"LLM JSON response"| S1AI
      S1AI -->|"raw result"| S1Svc
      S1Svc -->|"validate output"| S1Val
      S1Svc -.->|"log"| S1Log
      S1Log -.->|"write"| S1File
      S1Route <-->|"CategoryResponse"| S1Schema
      S1Route -->|"HTTP 200"| S1Client

      %% Error branches
      S1AI -.->|"AI call failure"| S1Err
      S1Val -.->|"invalid JSON/missing fields"| S1Err
      S1Err -.->|"HTTP error response"| S1Client
    end

    subgraph "Sequence 2: POST /generate-proposal"
      direction TB
      S2Client["Client"]:::external
      S2Route["Route: /generate-proposal"]:::route
      S2Schema["Schema: ProposalRequest/ProposalResponse"]:::schema
      S2Svc["ProposalService.generate_proposal()"]:::service
      S2AI["AIClient.complete(prompt)"]:::service
      S2Env["Env: GROQ_API_KEY"]:::config
      S2Groq["Groq LLM API"]:::external
      S2Val["ProposalValidator.validate(json)"]:::validator
      S2Log["Logger.log(prompt,response)"]:::util
      S2File[("ai_logs.json")]:::storage
      S2Err["Error Handling (HTTP 4xx/5xx)"]:::error

      S2Client -->|"request JSON"| S2Route
      S2Route -->|"parse"| S2Schema
      S2Route -->|"call"| S2Svc
      S2Svc -->|"prompt string"| S2AI
      S2Env -->|"configure"| S2AI
      S2AI -->|"HTTPS"| S2Groq
      S2Groq -->|"LLM JSON response"| S2AI
      S2AI -->|"raw result"| S2Svc
      S2Svc -->|"validate output"| S2Val
      S2Svc -.->|"log"| S2Log
      S2Log -.->|"write"| S2File
      S2Route <-->|"ProposalResponse"| S2Schema
      S2Route -->|"HTTP 200"| S2Client

      %% Error branches
      S2AI -.->|"AI call failure"| S2Err
      S2Val -.->|"invalid JSON/missing fields"| S2Err
      S2Err -.->|"HTTP error response"| S2Client
    end
  end

  %% =========================
  %% DevOps / Quality (secondary lane)
  %% =========================
  subgraph "DevOps / Quality (Non-runtime)"
    direction TB
    CI["CI: Lint Workflow"]:::devops
    Precommit["Pre-commit Hooks"]:::devops
    Req["Dependencies: requirements.txt"]:::devops
    PyProj["Build Metadata: pyproject.toml"]:::devops

    Precommit -->|"runs locally"| CI
    Req -->|"pins deps"| PyProj
  end

  %% =========================
  %% Click events (from component_mapping)
  %% =========================
  click App "https://github.com/rxz33/rayeva-ai-assignment/blob/main/app/main.py"
  click RouteCategory "https://github.com/rxz33/rayeva-ai-assignment/blob/main/app/routes/category.py"
  click RouteProposal "https://github.com/rxz33/rayeva-ai-assignment/blob/main/app/routes/proposal.py"
  click CatSchemas "https://github.com/rxz33/rayeva-ai-assignment/blob/main/app/schemas/category_schema.py"
  click PropSchemas "https://github.com/rxz33/rayeva-ai-assignment/blob/main/app/schemas/proposal_schema.py"
  click AIClient "https://github.com/rxz33/rayeva-ai-assignment/blob/main/app/services/ai_client.py"
  click CategorySvc "https://github.com/rxz33/rayeva-ai-assignment/blob/main/app/services/category_service.py"
  click ProposalSvc "https://github.com/rxz33/rayeva-ai-assignment/blob/main/app/services/proposal_service.py"
  click CatValidator "https://github.com/rxz33/rayeva-ai-assignment/blob/main/app/validators/category_validator.py"
  click PropValidator "https://github.com/rxz33/rayeva-ai-assignment/blob/main/app/validators/proposal_validator.py"
  click Logger "https://github.com/rxz33/rayeva-ai-assignment/blob/main/app/utils/logger.py"
  click DotEnv "https://github.com/rxz33/rayeva-ai-assignment/blob/main/.env.example"
  click CI "https://github.com/rxz33/rayeva-ai-assignment/blob/main/.github/workflows/lint.yml"
  click Precommit "https://github.com/rxz33/rayeva-ai-assignment/blob/main/.pre-commit-config.yaml"
  click Req "https://github.com/rxz33/rayeva-ai-assignment/blob/main/requirements.txt"
  click PyProj "https://github.com/rxz33/rayeva-ai-assignment/blob/main/pyproject.toml"

  %% =========================
  %% Styles (color is critical)
  %% =========================
  classDef container fill:#1f4e79,stroke:#0b2239,color:#ffffff,stroke-width:1.5px
  classDef route fill:#2b6cb0,stroke:#1a365d,color:#ffffff,stroke-width:1.2px
  classDef service fill:#2c5282,stroke:#1a365d,color:#ffffff,stroke-width:1.2px
  classDef validator fill:#2a4365,stroke:#1a365d,color:#ffffff,stroke-width:1.2px
  classDef schema fill:#2f855a,stroke:#1c4532,color:#ffffff,stroke-width:1.2px
  classDef util fill:#285e61,stroke:#134e4a,color:#ffffff,stroke-width:1.2px
  classDef external fill:#dd6b20,stroke:#7b341e,color:#ffffff,stroke-width:1.2px
  classDef storage fill:#718096,stroke:#1a202c,color:#ffffff,stroke-width:1.2px
  classDef config fill:#6b46c1,stroke:#2c1a7a,color:#ffffff,stroke-width:1.2px
  classDef devops fill:#4a5568,stroke:#1a202c,color:#ffffff,stroke-width:1.2px
  classDef error fill:#c53030,stroke:#742a2a,color:#ffffff,stroke-width:1.2px
```
