# s4rthakgupta/howgoodapp architecture

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

- Interactive diagram: https://gitdiagram.com/s4rthakgupta/howgoodapp
- Repository: https://github.com/s4rthakgupta/howgoodapp

## Overview

1. **Overall shape**
   - This repository is a **Next.js full-stack app** under `frontend/`, not a separate React frontend plus Express backend. The app uses the **App Router** for pages and also exposes **server-side API routes** from the same codebase.

2. **Primary runtime boundary**
   - The main boundary is between:
     - **Browser-rendered UI pages/components** in `src/app` and `src/components`
     - **Serverless/API execution** in `src/app/api/*`
   - That means page rendering, data fetching, and backend logic all live in one Next.js deployment unit.

3. **Page and route structure**
   - `src/app/page.tsx`, `about/page.tsx`, and `products/page.tsx` define the main user-facing routes.
   - `src/app/layout.tsx` provides the shared shell for the site.
   - `Nav.tsx` and `Footer.tsx` are likely mounted from the layout so every page shares the same chrome.

4. **Product domain subsystem**
   - The product-related flow is centered on:
     - `src/app/api/products/route.ts` for backend access
     - `src/app/products/page.tsx` for the UI
     - `src/components/ui/ProductCard.tsx` for rendering product entries
     - `src/lib/models/Product.ts` for the data model
   - This strongly suggests a MongoDB-backed product catalog, with the API route acting as the bridge between UI and database.

5. **AI analysis subsystem**
   - `src/app/api/analyze/route.ts` is the API endpoint for analysis requests.
   - `src/lib/aiUtils.ts` contains the AI integration logic, so the analysis pipeline likely goes:
     - user action in UI
     - request to `/api/analyze`
     - AI helper in `aiUtils`
     - response returned to the page
   - The README mentions sustainability scoring, so this endpoint appears to be the project’s core “intelligence” feature.

6. **Database access layer**
   - `src/lib/mongodb.ts` is the dedicated MongoDB connection layer.
   - `src/lib/models/Product.ts` defines the persistence model for product records.
   - This isolates database concerns from the API routes, which is useful for keeping route handlers thin and reusable.

7. **UI component layer**
   - The app uses reusable presentational components in `src/components/ui` such as `button`, `card`, `input`, and `carousel`.
   - These are typical design-system building blocks, likely supporting a **shadcn/ui + Tailwind-style** implementation.
   - `ProductCard.tsx` is domain-specific UI sitting on top of those primitives.

8. **Static assets and content**
   - `public/images` and `public/team` contain non-dynamic assets used by the pages, especially the About page and marketing-style sections.
   - This suggests the app combines product functionality with a strong informational/branding layer.

9. **Styling and app-wide presentation**
   - Global styling lives in `src/app/globals.css` and `src/styles/globals.css`.
   - Styling is centralized rather than embedded throughout pages, which supports a consistent visual system across routes.

10. **Request/middleware boundary**
   - `src/middleware.ts` introduces a cross-cutting request layer before routes are served.
   - Even without the implementation details, this file usually indicates route gating, redirects, header handling, or other request-level policy.

11. **Configuration and build tooling**
   - The repo uses standard Next.js tooling with `next.config.ts`, `tsconfig.json`, ESLint, PostCSS, and `package.json`.
   - `components.json` is a strong signal of shadcn-style component generation and a component-centric UI workflow.

12. **README vs. code reality**
   - The README describes a broader architecture with Express, Firebase, Clerk, and multiple hosting targets.
   - The file tree shows a more concrete implementation: **Next.js App Router + API routes + MongoDB + AI utility layer**.
   - For an architecture diagram, the file tree should be treated as the source of truth unless those extra services are added elsewhere.

Main entry points: [`frontend/src/app/layout.tsx`](https://github.com/s4rthakgupta/howgoodapp/blob/main/frontend/src/app/layout.tsx) (Layout), [`frontend/src/app/products/page.tsx`](https://github.com/s4rthakgupta/howgoodapp/blob/main/frontend/src/app/products/page.tsx) (Products), [`frontend/src/middleware.ts`](https://github.com/s4rthakgupta/howgoodapp/blob/main/frontend/src/middleware.ts) (Middleware), [`frontend/src/app/api/products/route.ts`](https://github.com/s4rthakgupta/howgoodapp/blob/main/frontend/src/app/api/products/route.ts) (Products API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Next.js app"]
  node_layout["Layout<br/>app shell<br/>[layout.tsx]"]
  node_home["Home<br/>route page<br/>[page.tsx]"]
  node_about["About<br/>route page<br/>[page.tsx]"]
  node_products_page["Products<br/>route page<br/>[page.tsx]"]
end

subgraph group_api["API routes"]
  node_products_api["Products API<br/>route handler<br/>[route.ts]"]
  node_analyze_api["Analyze API<br/>route handler<br/>[route.ts]"]
end

subgraph group_data["Domain data"]
  node_mongodb[("MongoDB<br/>connection layer<br/>[mongodb.ts]")]
  node_product_model["Product Model<br/>persistence model<br/>[Product.ts]"]
  node_ai_utils["AI Utils<br/>integration layer<br/>[aiUtils.ts]"]
end

subgraph group_ui["UI system"]
  node_nav["Nav<br/>site chrome<br/>[Nav.tsx]"]
  node_footer["Footer<br/>site chrome<br/>[Footer.tsx]"]
  node_product_card["Product Card<br/>domain ui<br/>[ProductCard.tsx]"]
  node_ui_primitives["UI Primitives<br/>design system<br/>[button.tsx]"]
end

subgraph group_infra["Infra & config"]
  node_middleware{{"Middleware<br/>request policy<br/>[middleware.ts]"}}
  node_styles["Global Styles<br/>styling<br/>[globals.css]"]
end

node_assets["Static Assets<br/>public assets"]

node_layout -->|"renders"| node_nav
node_layout -->|"renders"| node_footer
node_layout -->|"wraps"| node_home
node_layout -->|"wraps"| node_about
node_layout -->|"wraps"| node_products_page
node_home -.->|"calls"| node_analyze_api
node_products_page -.->|"fetches"| node_products_api
node_products_page -->|"uses"| node_product_card
node_products_page -->|"composes"| node_ui_primitives
node_about -.->|"uses"| node_assets
node_products_api -->|"connects"| node_mongodb
node_products_api -->|"uses"| node_product_model
node_analyze_api -->|"delegates"| node_ai_utils
node_analyze_api -.->|"reads"| node_mongodb
node_middleware -.->|"guards"| node_home
node_middleware -.->|"guards"| node_about
node_middleware -.->|"guards"| node_products_page
node_styles -->|"applies to"| node_layout
node_styles -->|"skins"| node_ui_primitives

click node_layout "https://github.com/s4rthakgupta/howgoodapp/blob/main/frontend/src/app/layout.tsx"
click node_home "https://github.com/s4rthakgupta/howgoodapp/blob/main/frontend/src/app/page.tsx"
click node_about "https://github.com/s4rthakgupta/howgoodapp/blob/main/frontend/src/app/about/page.tsx"
click node_products_page "https://github.com/s4rthakgupta/howgoodapp/blob/main/frontend/src/app/products/page.tsx"
click node_nav "https://github.com/s4rthakgupta/howgoodapp/blob/main/frontend/src/components/Nav.tsx"
click node_footer "https://github.com/s4rthakgupta/howgoodapp/blob/main/frontend/src/components/Footer.tsx"
click node_product_card "https://github.com/s4rthakgupta/howgoodapp/blob/main/frontend/src/components/ui/ProductCard.tsx"
click node_ui_primitives "https://github.com/s4rthakgupta/howgoodapp/blob/main/frontend/src/components/ui/button.tsx"
click node_products_api "https://github.com/s4rthakgupta/howgoodapp/blob/main/frontend/src/app/api/products/route.ts"
click node_analyze_api "https://github.com/s4rthakgupta/howgoodapp/blob/main/frontend/src/app/api/analyze/route.ts"
click node_mongodb "https://github.com/s4rthakgupta/howgoodapp/blob/main/frontend/src/lib/mongodb.ts"
click node_product_model "https://github.com/s4rthakgupta/howgoodapp/blob/main/frontend/src/lib/models/Product.ts"
click node_ai_utils "https://github.com/s4rthakgupta/howgoodapp/blob/main/frontend/src/lib/aiUtils.ts"
click node_middleware "https://github.com/s4rthakgupta/howgoodapp/blob/main/frontend/src/middleware.ts"
click node_styles "https://github.com/s4rthakgupta/howgoodapp/blob/main/frontend/src/app/globals.css"
click node_assets "https://github.com/s4rthakgupta/howgoodapp/tree/main/frontend/public/images"

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_layout,node_home,node_about,node_products_page toneBlue
class node_products_api,node_analyze_api toneAmber
class node_mongodb,node_product_model,node_ai_utils toneMint
class node_nav,node_footer,node_product_card,node_ui_primitives toneRose
class node_middleware,node_styles toneIndigo
class node_assets toneNeutral
```

## Components

### Next.js app

Browser UI, shared shell, and route pages

- [Layout](https://github.com/s4rthakgupta/howgoodapp/blob/main/frontend/src/app/layout.tsx): app shell · Shared site frame for all routes · `frontend/src/app/layout.tsx`
- [Home](https://github.com/s4rthakgupta/howgoodapp/blob/main/frontend/src/app/page.tsx): route page · Main landing page · `frontend/src/app/page.tsx`
- [About](https://github.com/s4rthakgupta/howgoodapp/blob/main/frontend/src/app/about/page.tsx): route page · Informational/about route · `frontend/src/app/about/page.tsx`
- [Products](https://github.com/s4rthakgupta/howgoodapp/blob/main/frontend/src/app/products/page.tsx): route page · Product catalog UI route · `frontend/src/app/products/page.tsx`

### API routes

Server-side request handlers inside the same Next.js deployment

- [Products API](https://github.com/s4rthakgupta/howgoodapp/blob/main/frontend/src/app/api/products/route.ts): route handler · Server route for product access · `frontend/src/app/api/products/route.ts`
- [Analyze API](https://github.com/s4rthakgupta/howgoodapp/blob/main/frontend/src/app/api/analyze/route.ts): route handler · Server route for analysis requests · `frontend/src/app/api/analyze/route.ts`

### Domain data

Persistence and AI integration layers

- [MongoDB](https://github.com/s4rthakgupta/howgoodapp/blob/main/frontend/src/lib/mongodb.ts): connection layer · Database connection and client setup · `frontend/src/lib/mongodb.ts`
- [Product Model](https://github.com/s4rthakgupta/howgoodapp/blob/main/frontend/src/lib/models/Product.ts): persistence model · Product schema/model definition · `frontend/src/lib/models/Product.ts`
- [AI Utils](https://github.com/s4rthakgupta/howgoodapp/blob/main/frontend/src/lib/aiUtils.ts): integration layer · AI/sustainability scoring helpers · `frontend/src/lib/aiUtils.ts`

### UI system

Reusable presentation components and design primitives

- [Nav](https://github.com/s4rthakgupta/howgoodapp/blob/main/frontend/src/components/Nav.tsx): site chrome · Top navigation shared across pages · `frontend/src/components/Nav.tsx`
- [Footer](https://github.com/s4rthakgupta/howgoodapp/blob/main/frontend/src/components/Footer.tsx): site chrome · Bottom site chrome shared across pages · `frontend/src/components/Footer.tsx`
- [Product Card](https://github.com/s4rthakgupta/howgoodapp/blob/main/frontend/src/components/ui/ProductCard.tsx): domain ui · Renders product entries in the catalog · `frontend/src/components/ui/ProductCard.tsx`
- [UI Primitives](https://github.com/s4rthakgupta/howgoodapp/blob/main/frontend/src/components/ui/button.tsx): design system · Reusable component building blocks · `frontend/src/components/ui/button.tsx`

### Infra & config

Middleware, styling, and build configuration

- [Middleware](https://github.com/s4rthakgupta/howgoodapp/blob/main/frontend/src/middleware.ts): request policy · Cross-cutting request handling before routes · `frontend/src/middleware.ts`
- [Global Styles](https://github.com/s4rthakgupta/howgoodapp/blob/main/frontend/src/app/globals.css): styling · App-wide CSS entrypoints · `frontend/src/app/globals.css`

### Other components

- [Static Assets](https://github.com/s4rthakgupta/howgoodapp/tree/main/frontend/public/images): public assets · Images and team media used by pages · `frontend/public/images`

## Connections

- Layout → Nav: renders · Shared chrome mounted in the site shell
- Layout → Footer: renders · Shared chrome mounted in the site shell
- Layout → Home: wraps · Shared app shell for the landing page
- Layout → About: wraps · Shared app shell for the about page
- Layout → Products: wraps · Shared app shell for the products page
- Home → Analyze API: calls · Home experience can submit analysis requests
- Products → Products API: fetches · Catalog page retrieves product data from the API
- Products → Product Card: uses · Catalog page renders product entries with domain card UI
- Products → UI Primitives: composes · Page uses shared UI building blocks
- About → Static Assets: uses · About/marketing content draws from static media
- Products API → MongoDB: connects · Product handler reads/writes through MongoDB layer
- Products API → Product Model: uses · API relies on product persistence model
- Analyze API → AI Utils: delegates · Analysis route forwards work to AI helper logic
- Analyze API → MongoDB: reads · Analysis may consult persisted data or connection layer
- Middleware → Home: guards · Request-level policy applies before route resolution
- Middleware → About: guards · Request-level policy applies before route resolution
- Middleware → Products: guards · Request-level policy applies before route resolution
- Global Styles → Layout: applies to · Global styles shape the app shell and route pages
- Global Styles → UI Primitives: skins · Shared styling also affects reusable primitives