# vikashkr96/cara architecture

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

- Interactive diagram: https://gitdiagram.com/vikashkr96/cara
- Repository: https://github.com/vikashkr96/cara

## Overview

1. **Overall shape**
   Cara is a **hybrid repo**: a largely **static e-commerce frontend** built with HTML/CSS/vanilla JavaScript, plus a **separate Python backend** under `backend/` that adds product and recommendation capabilities. In the current repo, the frontend appears to be the primary delivered experience, while the backend is an independent service with its own data and search pipeline.

2. **Frontend boundary**
   The main user-facing app is a set of **multiple standalone pages** (`index.html`, `shop.html`, `singleProduct.html`, `cart.html`, `checkout.html`, `login.html`, `register.html`, `track-order.html`, `try-on.html`, blog/about/contact/legal pages). These pages are linked together by browser navigation rather than a SPA router.

3. **Shared frontend assets**
   Styling is split across a common base (`style.css`, `global.css`) and page-specific CSS files such as `shop.css`, `cart.css`, `checkout.css`, `login.css`, `register.css`, `track-order.css`, `toast.css`, etc. Shared behavior is centralized in scripts like `navbar.js`, `app.js`, and `products.js`, with additional page scripts for login/register, forgot password, checkout, and tracking.

4. **Client-side interaction model**
   Most shopping interactions are implemented in the browser: browsing products, opening product details, managing the cart, quantity changes, toast notifications, authentication forms, and order tracking UI. The repository structure suggests these flows are **front-end driven** and likely use browser storage or in-page state, not a tightly coupled server-rendered backend.

5. **Content and marketing surface**
   A large portion of the frontend is informational and marketing-oriented: homepage, promotions, blog posts, about/community/contact, delivery/privacy/terms/license pages. These pages are static content surfaces supporting the commerce flow rather than separate application subsystems.

6. **Media and catalog assets**
   Product and brand imagery lives under `images/` and `assets/`, with subfolders for banners, products, blog, feature icons, payment visuals, people/team images, and garments. This is an important architectural boundary because the frontend is asset-heavy and depends on local static media rather than external CMS content.

7. **Backend service boundary**
   The backend in `backend/app/` is a **FastAPI-style Python service** with API modules for `products.py` and `recommendation.py`. This creates a clear separation between the browser UI and server-side domain logic, even if the README currently emphasizes the frontend more strongly than the integration.

8. **Backend domain layer**
   The backend is organized into `models.py`, `schemas.py`, and `database.py`, indicating a typical layered structure: persisted entities, request/response contracts, and database access/configuration. `main.py` is the service entrypoint that wires the API together.

9. **Recommendation subsystem**
   The backend’s most distinctive architecture is its **hybrid recommendation stack**:
   - `rules/engine.py` for rule-based filtering/selection
   - `vector_search/faiss_index.py` for similarity search
   - `scripts/precompute_embeddings.py` to build embeddings ahead of time  
   This suggests recommendations are generated by combining explicit business rules with semantic/vector retrieval, rather than simple CRUD-only APIs.

10. **Data initialization and offline prep**
   `scripts/seed_data.py` and `scripts/precompute_embeddings.py` show that part of the system is prepared **offline** before serving requests. That means the backend likely depends on pre-seeded catalog data and a prebuilt vector index, which is important for diagramming the startup and deployment path.

11. **Testing and validation**
   The backend includes `tests/test_rules.py`, so at least the recommendation/rules layer is unit-tested. On the frontend side, repo tooling (`eslint.config.mjs`, Prettier config, `.hintrc`) indicates code quality checks rather than application runtime dependencies.

12. **Repo duplication note**
   There is a duplicated `Cara-main/` subtree containing a near-complete copy of the frontend. For architecture diagrams, treat it as the same frontend codebase duplicated in the repo layout, not as a separate subsystem.

13. **Practical architecture diagram takeaway**
   The clearest diagram is: **browser-based static commerce UI** on one side, **Python recommendation/catalog API** on the other, with **local assets/content** feeding the UI and **offline preprocessing** supporting the backend’s search/recommendation logic. The current repo leans more toward a frontend-first e-commerce site with a backend foundation ready for deeper integration.

Main entry points: [`index.html`](https://github.com/vikashkr96/cara/blob/main/index.html) (Browser UI), [`backend/app/api/products.py`](https://github.com/vikashkr96/cara/blob/main/backend/app/api/products.py) (Product API), [`backend/app/api/recommendation.py`](https://github.com/vikashkr96/cara/blob/main/backend/app/api/recommendation.py) (Reco API), [`backend/app/vector_search/faiss_index.py`](https://github.com/vikashkr96/cara/blob/main/backend/app/vector_search/faiss_index.py) (Vector search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_browser_ui["Browser UI<br/>multi-page frontend<br/>[index.html]"]
  node_shop_page["Shop<br/>commerce page<br/>[shop.html]"]
  node_product_page["Product detail<br/>commerce page<br/>[singleProduct.html]"]
  node_checkout_page["Checkout<br/>commerce page<br/>[checkout.html]"]
  node_account_pages["Account pages<br/>auth pages<br/>[login.html]"]
  node_content_pages["Content pages<br/>marketing pages<br/>[blog.html]"]
  node_shared_styles["Shared styles<br/>css bundle<br/>[style.css]"]
  node_shared_scripts["Shared scripts<br/>client scripts<br/>[app.js]"]
  node_catalog_logic["Catalog logic<br/>client module<br/>[products.js]"]
end

subgraph group_media["Media"]
  node_media_assets[("Media assets<br/>static assets")]
end

subgraph group_backend["Backend"]
  node_service_entry["Service entry<br/>api app<br/>[main.py]"]
  node_product_api["Product API<br/>endpoint module<br/>[products.py]"]
  node_recommendation_api["Reco API<br/>endpoint module<br/>[recommendation.py]"]
  node_domain_models["Models<br/>domain layer<br/>[models.py]"]
  node_contracts["Schemas<br/>contracts<br/>[schemas.py]"]
  node_database_layer[("Database<br/>persistence<br/>[database.py]")]
  node_rule_engine["Rules<br/>[engine.py]"]
  node_vector_search["Vector search<br/>similarity index<br/>[faiss_index.py]"]
end

subgraph group_backend_pipeline["Offline prep"]
  node_seed_data["Seed data<br/>offline script<br/>[seed_data.py]"]
  node_embed_job["Embeddings<br/>offline job"]
end

node_browser_ui -->|"styles"| node_shared_styles
node_browser_ui -->|"behavior"| node_shared_scripts
node_browser_ui -->|"assets"| node_media_assets
node_browser_ui -->|"navigates"| node_shop_page
node_browser_ui -->|"navigates"| node_product_page
node_browser_ui -->|"navigates"| node_checkout_page
node_browser_ui -->|"navigates"| node_account_pages
node_browser_ui -->|"navigates"| node_content_pages
node_shared_scripts -->|"loads"| node_catalog_logic
node_service_entry -->|"routes"| node_product_api
node_service_entry -->|"routes"| node_recommendation_api
node_product_api -->|"uses"| node_domain_models
node_product_api -->|"validates"| node_contracts
node_product_api -->|"reads/writes"| node_database_layer
node_recommendation_api -->|"applies"| node_rule_engine
node_recommendation_api -->|"queries"| node_vector_search
node_rule_engine -.->|"combines"| node_vector_search
node_seed_data -->|"initializes"| node_database_layer
node_embed_job -->|"builds"| node_vector_search
node_embed_job -.->|"depends on"| node_seed_data

click node_browser_ui "https://github.com/vikashkr96/cara/blob/main/index.html"
click node_shop_page "https://github.com/vikashkr96/cara/blob/main/shop.html"
click node_product_page "https://github.com/vikashkr96/cara/blob/main/singleProduct.html"
click node_checkout_page "https://github.com/vikashkr96/cara/blob/main/checkout.html"
click node_account_pages "https://github.com/vikashkr96/cara/blob/main/login.html"
click node_content_pages "https://github.com/vikashkr96/cara/blob/main/blog.html"
click node_shared_styles "https://github.com/vikashkr96/cara/blob/main/style.css"
click node_shared_scripts "https://github.com/vikashkr96/cara/blob/main/app.js"
click node_catalog_logic "https://github.com/vikashkr96/cara/blob/main/products.js"
click node_media_assets "https://github.com/vikashkr96/cara/tree/main/images"
click node_service_entry "https://github.com/vikashkr96/cara/blob/main/backend/app/main.py"
click node_product_api "https://github.com/vikashkr96/cara/blob/main/backend/app/api/products.py"
click node_recommendation_api "https://github.com/vikashkr96/cara/blob/main/backend/app/api/recommendation.py"
click node_domain_models "https://github.com/vikashkr96/cara/blob/main/backend/app/models.py"
click node_contracts "https://github.com/vikashkr96/cara/blob/main/backend/app/schemas.py"
click node_database_layer "https://github.com/vikashkr96/cara/blob/main/backend/app/database.py"
click node_rule_engine "https://github.com/vikashkr96/cara/blob/main/backend/app/rules/engine.py"
click node_vector_search "https://github.com/vikashkr96/cara/blob/main/backend/app/vector_search/faiss_index.py"
click node_seed_data "https://github.com/vikashkr96/cara/blob/main/backend/scripts/seed_data.py"
click node_embed_job "https://github.com/vikashkr96/cara/blob/main/backend/scripts/precompute_embeddings.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_browser_ui,node_shop_page,node_product_page,node_checkout_page,node_account_pages,node_content_pages,node_shared_styles,node_shared_scripts,node_catalog_logic toneBlue
class node_media_assets toneAmber
class node_service_entry,node_product_api,node_recommendation_api,node_domain_models,node_contracts,node_database_layer,node_rule_engine,node_vector_search toneMint
class node_seed_data,node_embed_job toneRose
```

## Components

### Frontend

Static multi-page commerce UI and shared browser-side behavior.

- [Browser UI](https://github.com/vikashkr96/cara/blob/main/index.html): multi-page frontend · Entry point for the static storefront and marketing pages. · `index.html`
- [Shop](https://github.com/vikashkr96/cara/blob/main/shop.html): commerce page · Product browsing and storefront listing page. · `shop.html`
- [Product detail](https://github.com/vikashkr96/cara/blob/main/singleProduct.html): commerce page · Single-product view for item details and actions. · `singleProduct.html`
- [Checkout](https://github.com/vikashkr96/cara/blob/main/checkout.html): commerce page · Cart review and order completion flow. · `checkout.html`
- [Account pages](https://github.com/vikashkr96/cara/blob/main/login.html): auth pages · Login, registration, password recovery, and order tracking screens. · `login.html`
- [Content pages](https://github.com/vikashkr96/cara/blob/main/blog.html): marketing pages · Blog, about, contact, policy, and promotional content surfaces. · `blog.html`
- [Shared styles](https://github.com/vikashkr96/cara/blob/main/style.css): css bundle · Base styling shared across pages. · `style.css`
- [Shared scripts](https://github.com/vikashkr96/cara/blob/main/app.js): client scripts · Common browser logic used across the storefront. · `app.js`
- [Catalog logic](https://github.com/vikashkr96/cara/blob/main/products.js): client module · Product listing and browsing behavior in the browser. · `products.js`

### Media

Local images, banners, product photos, and brand assets consumed by the frontend.

- [Media assets](https://github.com/vikashkr96/cara/tree/main/images): static assets · Product, banner, blog, and supporting imagery/videos used by the UI. · `images`

### Backend

Python API service for catalog and recommendation features.

- [Service entry](https://github.com/vikashkr96/cara/blob/main/backend/app/main.py): api app · Backend application bootstrap and routing assembly. · `backend/app/main.py`
- [Product API](https://github.com/vikashkr96/cara/blob/main/backend/app/api/products.py): endpoint module · Catalog-related API surface. · `backend/app/api/products.py`
- [Reco API](https://github.com/vikashkr96/cara/blob/main/backend/app/api/recommendation.py): endpoint module · Recommendation-facing API surface. · `backend/app/api/recommendation.py`
- [Models](https://github.com/vikashkr96/cara/blob/main/backend/app/models.py): domain layer · Persisted entities and core backend domain objects. · `backend/app/models.py`
- [Schemas](https://github.com/vikashkr96/cara/blob/main/backend/app/schemas.py): contracts · Request and response validation contracts. · `backend/app/schemas.py`
- [Database](https://github.com/vikashkr96/cara/blob/main/backend/app/database.py): persistence · Database configuration and access layer. · `backend/app/database.py`
- [Rules](https://github.com/vikashkr96/cara/blob/main/backend/app/rules/engine.py): recommendation rules · Rule-based filtering and selection logic. · `backend/app/rules/engine.py`
- [Vector search](https://github.com/vikashkr96/cara/blob/main/backend/app/vector_search/faiss_index.py): similarity index · FAISS-backed semantic retrieval index. · `backend/app/vector_search/faiss_index.py`

### Offline prep

Data seeding and embedding precomputation used by the backend.

- [Seed data](https://github.com/vikashkr96/cara/blob/main/backend/scripts/seed_data.py): offline script · Initial catalog data loading for the backend. · `backend/scripts/seed_data.py`
- [Embeddings](https://github.com/vikashkr96/cara/blob/main/backend/scripts/precompute_embeddings.py): offline job · Precomputes embeddings for vector search. · `backend/scripts/precompute_embeddings.py`

## Connections

- Browser UI → Shared styles: styles · Pages share the base stylesheet.
- Browser UI → Shared scripts: behavior · Common browser interactions are centralized in shared scripts.
- Browser UI → Media assets: assets · The storefront renders local media and imagery.
- Browser UI → Shop: navigates · Browser navigation moves through standalone pages.
- Browser UI → Product detail: navigates · Product detail is a separate page in the storefront.
- Browser UI → Checkout: navigates · Checkout is its own page boundary.
- Browser UI → Account pages: navigates · Authentication and tracking screens are separate pages.
- Browser UI → Content pages: navigates · Marketing and informational pages are part of the same site.
- Shared scripts → Catalog logic: loads · Shared UI code delegates product handling to catalog logic.
- Service entry → Product API: routes · The backend entrypoint wires catalog endpoints.
- Service entry → Reco API: routes · The backend entrypoint wires recommendation endpoints.
- Product API → Models: uses · Product endpoints operate on backend domain objects.
- Product API → Schemas: validates · Product requests and responses use schema contracts.
- Product API → Database: reads/writes · Catalog operations persist through the database layer.
- Reco API → Rules: applies · Recommendation endpoints invoke rule-based selection.
- Reco API → Vector search: queries · Recommendation endpoints query the similarity index.
- Rules → Vector search: combines · Rules and semantic retrieval work together in recommendations.
- Seed data → Database: initializes · Seed script prepares the backend data store.
- Embeddings → Vector search: builds · Embedding precomputation populates the search index.
- Embeddings → Seed data: depends on · Embedding generation assumes seeded catalog data.
