# codepath/ai201-project2-fitfindr-starter architecture

> Architecture diagram of the GitHub repository codepath/ai201-project2-fitfindr-starter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/codepath/ai201-project2-fitfindr-starter
- Repository: https://github.com/codepath/ai201-project2-fitfindr-starter

## Overview

1. **Project purpose**
   - This repo is a starter kit for an AI styling assistant called **FitFindr**.
   - The core job is to take a user query plus their wardrobe, search a small catalog of secondhand listings, and produce an outfit or “fit card” response.

2. **Main runtime entry points**
   - `app.py` is the likely top-level application entry point for running the experience.
   - `agent.py` appears to contain the orchestration logic that interprets user intent and decides which tools to call.
   - `tools.py` is the functional boundary between the agent and the task-specific capabilities.

3. **Agent orchestration layer**
   - The agent layer is the control plane: it receives a natural-language request, reasons over it, and invokes tools in sequence.
   - Based on the README, the expected flow is: user query → listing search / wardrobe-aware suggestion → fit card creation.
   - This layer is where integration with the Groq API is expected, since the setup instructions require `GROQ_API_KEY`.

4. **Tooling layer**
   - `tools.py` is the primary capability surface and must expose the tools documented in the README:
     - `search_listings`
     - `suggest_outfit`
     - `create_fit_card`
   - The README emphasizes that the documented signatures must match the code exactly, so this file is part of the grading contract and a clear subsystem boundary.

5. **Data layer**
   - `data/listings.json` is the catalog of mock secondhand inventory.
   - `data/wardrobe_schema.json` defines the structure of the user wardrobe, plus example and empty templates.
   - These files are static inputs, not live services; the architecture is centered on local dataset loading rather than external product APIs.

6. **Shared data-loading utilities**
   - `utils/data_loader.py` is the reusable adapter for reading the JSON assets into Python objects.
   - It likely abstracts file-path handling and gives the rest of the code a stable interface for loading listings and wardrobe examples.
   - This keeps file I/O out of the agent and tool logic.

7. **Data flow through the system**
   - The user provides a query to the app.
   - The agent interprets intent and pulls structured data from the loaded listings and wardrobe state.
   - Tool functions operate on that in-memory data to filter, rank, or assemble recommendations.
   - A final fit card is produced and returned to the user.

8. **Domain model boundaries**
   - The repository separates two main data domains:
     - **Marketplace inventory**: secondhand listings with category, style, size, condition, price, colors, brand, and platform.
     - **User wardrobe**: items following the schema in `wardrobe_schema.json`.
   - Outfit logic sits at the intersection of these two domains, combining existing wardrobe items with candidate listings.

9. **External dependency boundary**
   - The only material external service implied by the repo is **Groq** for LLM-powered agent reasoning.
   - Everything else appears local and file-based, which means the system is mostly deterministic outside of model calls.
   - `requirements.txt` defines the Python runtime dependencies needed for this stack.

10. **Planning and specification artifacts**
   - `planning.md` is a design/specification artifact, not runtime code.
   - The README makes it clear the planning document should be completed before implementation, so it serves as the architectural contract for the student’s chosen agent design.
   - This file helps explain intended behavior even if the implementation is not yet finished.

11. **Likely deployment shape**
   - The repo looks like a single-process Python application rather than a distributed system.
   - There is no evidence of databases, queues, or microservices.
   - The architecture diagram should therefore show one application boundary with local JSON assets and an LLM API dependency.

12. **What to draw in an architecture diagram**
   - Show `app.py` as the user-facing entry point.
   - Show `agent.py` as the orchestration engine.
   - Show `tools.py` as the callable action layer.
   - Show `utils/data_loader.py` as the data access helper.
   - Show `data/listings.json` and `data/wardrobe_schema.json` as static inputs.
   - Show Groq as the external model service.

Main entry points: [`tools.py`](https://github.com/codepath/ai201-project2-fitfindr-starter/blob/main/tools.py) (Tools), [`agent.py`](https://github.com/codepath/ai201-project2-fitfindr-starter/blob/main/agent.py) (Agent), [`utils/data_loader.py`](https://github.com/codepath/ai201-project2-fitfindr-starter/blob/main/utils/data_loader.py) (Data loader), [`data/listings.json`](https://github.com/codepath/ai201-project2-fitfindr-starter/blob/main/data/listings.json) (Listings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Application"]
  node_app["App entry<br/>entrypoint<br/>[app.py]"]
  node_agent{{"Agent<br/>orchestrator<br/>[agent.py]"}}
  node_tools["Tools<br/>capability layer<br/>[tools.py]"]
  node_loader["Data loader<br/>adapter<br/>[data_loader.py]"]
  node_search_listings["Search listings<br/>tool<br/>[tools.py]"]
  node_suggest_outfit["Suggest outfit<br/>tool<br/>[tools.py]"]
  node_create_fit_card["Fit card<br/>tool<br/>[tools.py]"]
end

subgraph group_data["Local Data"]
  node_listings[("Listings<br/>catalog json<br/>[listings.json]")]
  node_wardrobe_schema["Wardrobe schema<br/>schema json"]
end

subgraph group_external["External Service"]
  node_groq(("Groq API<br/>llm service"))
end

subgraph group_docs["Spec Artifacts"]
  node_planning["Planning<br/>spec doc<br/>[planning.md]"]
  node_requirements["Deps<br/>[requirements.txt]"]
end

node_app -->|"start request"| node_agent
node_agent -->|"reasoning"| node_groq
node_agent -->|"invoke"| node_tools
node_tools -->|"load data"| node_loader
node_loader -->|"read"| node_listings
node_loader -->|"read"| node_wardrobe_schema
node_tools -->|"expose"| node_search_listings
node_tools -->|"expose"| node_suggest_outfit
node_tools -->|"expose"| node_create_fit_card
node_search_listings -->|"filter"| node_listings
node_suggest_outfit -->|"match"| node_listings
node_suggest_outfit -->|"combine"| node_wardrobe_schema
node_create_fit_card -->|"return"| node_agent
node_planning -.->|"design input"| node_agent
node_requirements -.->|"runtime deps"| node_app

click node_app "https://github.com/codepath/ai201-project2-fitfindr-starter/blob/main/app.py"
click node_agent "https://github.com/codepath/ai201-project2-fitfindr-starter/blob/main/agent.py"
click node_tools "https://github.com/codepath/ai201-project2-fitfindr-starter/blob/main/tools.py"
click node_loader "https://github.com/codepath/ai201-project2-fitfindr-starter/blob/main/utils/data_loader.py"
click node_search_listings "https://github.com/codepath/ai201-project2-fitfindr-starter/blob/main/tools.py"
click node_suggest_outfit "https://github.com/codepath/ai201-project2-fitfindr-starter/blob/main/tools.py"
click node_create_fit_card "https://github.com/codepath/ai201-project2-fitfindr-starter/blob/main/tools.py"
click node_listings "https://github.com/codepath/ai201-project2-fitfindr-starter/blob/main/data/listings.json"
click node_wardrobe_schema "https://github.com/codepath/ai201-project2-fitfindr-starter/blob/main/data/wardrobe_schema.json"
click node_planning "https://github.com/codepath/ai201-project2-fitfindr-starter/blob/main/planning.md"
click node_requirements "https://github.com/codepath/ai201-project2-fitfindr-starter/blob/main/requirements.txt"

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_app,node_agent,node_tools,node_loader,node_search_listings,node_suggest_outfit,node_create_fit_card toneBlue
class node_listings,node_wardrobe_schema toneAmber
class node_groq toneMint
class node_planning,node_requirements toneRose
```

## Components

### Application

Single-process Python runtime that accepts requests and produces fit cards.

- [App entry](https://github.com/codepath/ai201-project2-fitfindr-starter/blob/main/app.py): entrypoint · Top-level application launcher for the FitFindr experience. · `app.py`
- [Agent](https://github.com/codepath/ai201-project2-fitfindr-starter/blob/main/agent.py): orchestrator · Interprets user intent and coordinates tool calls. · `agent.py`
- [Tools](https://github.com/codepath/ai201-project2-fitfindr-starter/blob/main/tools.py): capability layer · Task-specific functions for search, outfit suggestion, and fit card creation. · `tools.py`
- [Data loader](https://github.com/codepath/ai201-project2-fitfindr-starter/blob/main/utils/data_loader.py): adapter · Shared helper for reading JSON assets into Python objects. · `utils/data_loader.py`
- [Search listings](https://github.com/codepath/ai201-project2-fitfindr-starter/blob/main/tools.py): tool · Finds relevant secondhand items from the catalog. · `tools.py`
- [Suggest outfit](https://github.com/codepath/ai201-project2-fitfindr-starter/blob/main/tools.py): tool · Combines wardrobe state and candidate listings into outfit ideas. · `tools.py`
- [Fit card](https://github.com/codepath/ai201-project2-fitfindr-starter/blob/main/tools.py): tool · Formats the final style recommendation for the user. · `tools.py`

### Local Data

Static JSON assets used for listings and wardrobe structure.

- [Listings](https://github.com/codepath/ai201-project2-fitfindr-starter/blob/main/data/listings.json): catalog json · Mock secondhand inventory used as search input. · `data/listings.json`
- [Wardrobe schema](https://github.com/codepath/ai201-project2-fitfindr-starter/blob/main/data/wardrobe_schema.json): schema json · Wardrobe structure plus example and empty templates. · `data/wardrobe_schema.json`

### External Service

LLM provider used for agent reasoning.

- **Groq API**: llm service · External model service for agent reasoning and tool orchestration.

### Spec Artifacts

Planning and dependency files that shape implementation.

- [Planning](https://github.com/codepath/ai201-project2-fitfindr-starter/blob/main/planning.md): spec doc · Design/specification artifact for the intended agent behavior. · `planning.md`
- [Deps](https://github.com/codepath/ai201-project2-fitfindr-starter/blob/main/requirements.txt): python deps · Runtime dependency manifest for the application stack. · `requirements.txt`

## Connections

- App entry → Agent: start request · Application hands user input to the orchestration layer.
- Agent → Groq API: reasoning · Agent uses the model service for intent interpretation and planning.
- Agent → Tools: invoke · Agent selects and calls task-specific capabilities.
- Tools → Data loader: load data · Tools read structured JSON through the shared loader.
- Data loader → Listings: read · Catalog data is loaded from local JSON.
- Data loader → Wardrobe schema: read · Wardrobe structure and templates are loaded from local JSON.
- Tools → Search listings: expose · Search capability is part of the tool surface.
- Tools → Suggest outfit: expose · Outfit suggestion capability is part of the tool surface.
- Tools → Fit card: expose · Fit card creation capability is part of the tool surface.
- Search listings → Listings: filter · Search operates on the marketplace catalog.
- Suggest outfit → Listings: match · Outfit suggestion considers candidate items from the catalog.
- Suggest outfit → Wardrobe schema: combine · Outfit logic is grounded in wardrobe structure.
- Fit card → Agent: return · Final composed recommendation is returned through the agent flow.
- Planning → Agent: design input · Planning document specifies intended orchestration behavior.
- Deps → App entry: runtime deps · Dependency manifest supports the application runtime.