How vikashkr96/cara works
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 Browser UI · products.py Product API · recommendation.py Reco API · faiss_index.py Vector search
Components 20
Frontend
Static multi-page commerce UI and shared browser-side behavior.
- Browser UI · Entry point for the static storefront and marketing pages.
index.html - Shop · Product browsing and storefront listing page.
shop.html - Product detail · Single-product view for item details and actions.
singleProduct.html - Checkout · Cart review and order completion flow.
checkout.html - Account pages · Login, registration, password recovery, and order tracking screens.
login.html - Content pages · Blog, about, contact, policy, and promotional content surfaces.
blog.html - Shared styles · Base styling shared across pages.
style.css - Shared scripts · Common browser logic used across the storefront.
app.js - Catalog logic · 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 · Product, banner, blog, and supporting imagery/videos used by the UI.
images
Backend
Python API service for catalog and recommendation features.
- Service entry · Backend application bootstrap and routing assembly.
backend/app/main.py - Product API · Catalog-related API surface.
backend/app/api/products.py - Reco API · Recommendation-facing API surface.
backend/app/api/recommendation.py - Models · Persisted entities and core backend domain objects.
backend/app/models.py - Schemas · Request and response validation contracts.
backend/app/schemas.py - Database · Database configuration and access layer.
backend/app/database.py - Rules · Rule-based filtering and selection logic.
backend/app/rules/engine.py - Vector search · 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 · Initial catalog data loading for the backend.
backend/scripts/seed_data.py - Embeddings · Precomputes embeddings for vector search.
backend/scripts/precompute_embeddings.py
Connections 20
- 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.