How rxz33/rayeva-ai-assignment works
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).