# ahmad-codemaster/geomarket architecture

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

- Interactive diagram: https://gitdiagram.com/ahmad-codemaster/geomarket
- Repository: https://github.com/ahmad-codemaster/geomarket

## Overview

GeoMarket is a location-first, multi-vendor marketplace. Customers set a location, discover eligible nearby stores and inventory, maintain a single-store cart, and check out as a guest or signed-in user; vendors manage stores, stock, and fulfillment, while admins oversee the platform. The graph combines sampled controller/service calls with README-documented product capabilities. Several client and backend subsystems are represented by their exact tree paths, but unsampled internal wiring is intentionally omitted.

Main entry points: [`server/src/lib/prisma.ts`](https://github.com/ahmad-codemaster/geomarket/blob/main/server/src/lib/prisma.ts) (PostgreSQL and PostGIS), [`client/src/lib/api.ts`](https://github.com/ahmad-codemaster/geomarket/blob/main/client/src/lib/api.ts) (API client), [`client/src/App.tsx`](https://github.com/ahmad-codemaster/geomarket/blob/main/client/src/App.tsx) (Web application), [`server/src/modules/order/order.service.ts`](https://github.com/ahmad-codemaster/geomarket/blob/main/server/src/modules/order/order.service.ts) (Checkout and orders)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Customer application"]
  node_app["Web application<br/>[App.tsx]"]
  node_api["API client<br/>[api.ts]"]
  node_location_ui["Location selection"]
  node_location_state["Location state<br/>[location.store.ts]"]
  node_discovery_hook["Discovery queries<br/>[useDiscovery.ts]"]
  node_cart_hook["Cart queries<br/>[useCart.ts]"]
  node_order_hook["Order queries<br/>[useOrders.ts]"]
end

subgraph group_commerce["Commerce services"]
  node_discovery_controller["Discovery API"]
  node_discovery_service["Proximity discovery"]
  node_discovery_repo["Discovery data access"]
  node_location_service["Geocoding service"]
  node_location_provider["Geocoding providers"]
  node_cart_controller["Cart API<br/>[cart.controller.ts]"]
  node_cart_service["Cart rules<br/>[cart.service.ts]"]
  node_checkout["Checkout and orders<br/>[order.service.ts]"]
  node_order_fsm["Order lifecycle<br/>[order.fsm.ts]"]
end

subgraph group_operations["Marketplace operations"]
  node_store_ops["Store management<br/>[store.service.ts]"]
  node_product_ops["Inventory management<br/>[product.service.ts]"]
  node_reviews["Verified reviews<br/>[review.service.ts]"]
  node_analytics["Analytics"]
  node_admin["Platform administration"]
end

subgraph group_platform["Shared platform"]
  node_auth_controller["Authentication API<br/>[auth.controller.ts]"]
  node_auth_service["Authentication<br/>[auth.service.ts]"]
  node_database[("PostgreSQL and PostGIS<br/>[prisma.ts]")]
end

node_customer(("Customer"))

node_customer -->|"uses"| node_app
node_app -->|"selects location"| node_location_ui
node_location_ui -->|"updates location"| node_location_state
node_app -->|"browses nearby"| node_discovery_hook
node_discovery_hook -->|"requests discovery"| node_api
node_api -->|"calls API"| node_discovery_controller
node_discovery_controller -->|"delegates"| node_discovery_service
node_discovery_service -->|"queries stores"| node_discovery_repo
node_discovery_repo -->|"reads spatial data"| node_database
node_app -->|"manages cart"| node_cart_hook
node_cart_hook -->|"calls cart API"| node_api
node_api -->|"calls API"| node_cart_controller
node_cart_controller -->|"delegates"| node_cart_service
node_cart_service -->|"reads and writes"| node_database
node_app -->|"tracks orders"| node_order_hook
node_order_hook -->|"calls order API"| node_api
node_api -->|"submits checkout"| node_checkout
node_checkout -->|"creates orders"| node_database
node_checkout -->|"checks transitions"| node_order_fsm
node_auth_controller -->|"delegates"| node_auth_service
node_auth_controller -->|"transfers guest cart"| node_cart_service
node_auth_service -->|"reads and writes"| node_database
node_location_service -.->|"geocodes with"| node_location_provider
node_location_service -->|"reads location data"| node_database
node_store_ops -->|"manages stores"| node_database
node_product_ops -->|"manages inventory"| node_database
node_reviews -->|"reads and writes"| node_database
node_analytics -->|"queries metrics"| node_database
node_admin -->|"queries platform data"| node_database

click node_app "https://github.com/ahmad-codemaster/geomarket/blob/main/client/src/App.tsx"
click node_api "https://github.com/ahmad-codemaster/geomarket/blob/main/client/src/lib/api.ts"
click node_location_ui "https://github.com/ahmad-codemaster/geomarket/blob/main/client/src/components/location/LocationPickerModal.tsx"
click node_location_state "https://github.com/ahmad-codemaster/geomarket/blob/main/client/src/store/location.store.ts"
click node_discovery_hook "https://github.com/ahmad-codemaster/geomarket/blob/main/client/src/hooks/useDiscovery.ts"
click node_cart_hook "https://github.com/ahmad-codemaster/geomarket/blob/main/client/src/hooks/useCart.ts"
click node_order_hook "https://github.com/ahmad-codemaster/geomarket/blob/main/client/src/hooks/useOrders.ts"
click node_discovery_controller "https://github.com/ahmad-codemaster/geomarket/blob/main/server/src/modules/discovery/discovery.controller.ts"
click node_discovery_service "https://github.com/ahmad-codemaster/geomarket/blob/main/server/src/modules/discovery/discovery.service.ts"
click node_discovery_repo "https://github.com/ahmad-codemaster/geomarket/blob/main/server/src/modules/discovery/discovery.repository.ts"
click node_location_service "https://github.com/ahmad-codemaster/geomarket/blob/main/server/src/modules/location/location.service.ts"
click node_location_provider "https://github.com/ahmad-codemaster/geomarket/blob/main/server/src/modules/location/providers/nominatim.provider.ts"
click node_cart_controller "https://github.com/ahmad-codemaster/geomarket/blob/main/server/src/modules/cart/cart.controller.ts"
click node_cart_service "https://github.com/ahmad-codemaster/geomarket/blob/main/server/src/modules/cart/cart.service.ts"
click node_checkout "https://github.com/ahmad-codemaster/geomarket/blob/main/server/src/modules/order/order.service.ts"
click node_order_fsm "https://github.com/ahmad-codemaster/geomarket/blob/main/server/src/modules/order/order.fsm.ts"
click node_auth_controller "https://github.com/ahmad-codemaster/geomarket/blob/main/server/src/modules/auth/auth.controller.ts"
click node_auth_service "https://github.com/ahmad-codemaster/geomarket/blob/main/server/src/modules/auth/auth.service.ts"
click node_store_ops "https://github.com/ahmad-codemaster/geomarket/blob/main/server/src/modules/store/store.service.ts"
click node_product_ops "https://github.com/ahmad-codemaster/geomarket/blob/main/server/src/modules/product/product.service.ts"
click node_reviews "https://github.com/ahmad-codemaster/geomarket/blob/main/server/src/modules/review/review.service.ts"
click node_analytics "https://github.com/ahmad-codemaster/geomarket/blob/main/server/src/modules/analytics/analytics.service.ts"
click node_admin "https://github.com/ahmad-codemaster/geomarket/blob/main/server/src/modules/admin/admin.controller.ts"
click node_database "https://github.com/ahmad-codemaster/geomarket/blob/main/server/src/lib/prisma.ts"

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_api,node_location_ui,node_location_state,node_discovery_hook,node_cart_hook,node_order_hook toneBlue
class node_discovery_controller,node_discovery_service,node_discovery_repo,node_location_service,node_location_provider,node_cart_controller,node_cart_service,node_checkout,node_order_fsm toneAmber
class node_store_ops,node_product_ops,node_reviews,node_analytics,node_admin toneMint
class node_auth_controller,node_auth_service,node_database toneRose
class node_customer toneIndigo
```

## Components

### Customer application

- [Web application](https://github.com/ahmad-codemaster/geomarket/blob/main/client/src/App.tsx): `client/src/App.tsx`
- [API client](https://github.com/ahmad-codemaster/geomarket/blob/main/client/src/lib/api.ts): `client/src/lib/api.ts`
- [Location selection](https://github.com/ahmad-codemaster/geomarket/blob/main/client/src/components/location/LocationPickerModal.tsx): `client/src/components/location/LocationPickerModal.tsx`
- [Location state](https://github.com/ahmad-codemaster/geomarket/blob/main/client/src/store/location.store.ts): `client/src/store/location.store.ts`
- [Discovery queries](https://github.com/ahmad-codemaster/geomarket/blob/main/client/src/hooks/useDiscovery.ts): `client/src/hooks/useDiscovery.ts`
- [Cart queries](https://github.com/ahmad-codemaster/geomarket/blob/main/client/src/hooks/useCart.ts): `client/src/hooks/useCart.ts`
- [Order queries](https://github.com/ahmad-codemaster/geomarket/blob/main/client/src/hooks/useOrders.ts): `client/src/hooks/useOrders.ts`

### Commerce services

- [Discovery API](https://github.com/ahmad-codemaster/geomarket/blob/main/server/src/modules/discovery/discovery.controller.ts): `server/src/modules/discovery/discovery.controller.ts`
- [Proximity discovery](https://github.com/ahmad-codemaster/geomarket/blob/main/server/src/modules/discovery/discovery.service.ts): `server/src/modules/discovery/discovery.service.ts`
- [Discovery data access](https://github.com/ahmad-codemaster/geomarket/blob/main/server/src/modules/discovery/discovery.repository.ts): `server/src/modules/discovery/discovery.repository.ts`
- [Geocoding service](https://github.com/ahmad-codemaster/geomarket/blob/main/server/src/modules/location/location.service.ts): `server/src/modules/location/location.service.ts`
- [Geocoding providers](https://github.com/ahmad-codemaster/geomarket/blob/main/server/src/modules/location/providers/nominatim.provider.ts): `server/src/modules/location/providers/nominatim.provider.ts`
- [Cart API](https://github.com/ahmad-codemaster/geomarket/blob/main/server/src/modules/cart/cart.controller.ts): `server/src/modules/cart/cart.controller.ts`
- [Cart rules](https://github.com/ahmad-codemaster/geomarket/blob/main/server/src/modules/cart/cart.service.ts): `server/src/modules/cart/cart.service.ts`
- [Checkout and orders](https://github.com/ahmad-codemaster/geomarket/blob/main/server/src/modules/order/order.service.ts): `server/src/modules/order/order.service.ts`
- [Order lifecycle](https://github.com/ahmad-codemaster/geomarket/blob/main/server/src/modules/order/order.fsm.ts): `server/src/modules/order/order.fsm.ts`

### Marketplace operations

- [Store management](https://github.com/ahmad-codemaster/geomarket/blob/main/server/src/modules/store/store.service.ts): `server/src/modules/store/store.service.ts`
- [Inventory management](https://github.com/ahmad-codemaster/geomarket/blob/main/server/src/modules/product/product.service.ts): `server/src/modules/product/product.service.ts`
- [Verified reviews](https://github.com/ahmad-codemaster/geomarket/blob/main/server/src/modules/review/review.service.ts): `server/src/modules/review/review.service.ts`
- [Analytics](https://github.com/ahmad-codemaster/geomarket/blob/main/server/src/modules/analytics/analytics.service.ts): `server/src/modules/analytics/analytics.service.ts`
- [Platform administration](https://github.com/ahmad-codemaster/geomarket/blob/main/server/src/modules/admin/admin.controller.ts): `server/src/modules/admin/admin.controller.ts`

### Shared platform

- [Authentication API](https://github.com/ahmad-codemaster/geomarket/blob/main/server/src/modules/auth/auth.controller.ts): `server/src/modules/auth/auth.controller.ts`
- [Authentication](https://github.com/ahmad-codemaster/geomarket/blob/main/server/src/modules/auth/auth.service.ts): `server/src/modules/auth/auth.service.ts`
- [PostgreSQL and PostGIS](https://github.com/ahmad-codemaster/geomarket/blob/main/server/src/lib/prisma.ts): `server/src/lib/prisma.ts`

### Other components

- **Customer**

## Connections

- Customer → Web application: uses
- Web application → Location selection: selects location
- Location selection → Location state: updates location
- Web application → Discovery queries: browses nearby
- Discovery queries → API client: requests discovery
- API client → Discovery API: calls API
- Discovery API → Proximity discovery: delegates
- Proximity discovery → Discovery data access: queries stores
- Discovery data access → PostgreSQL and PostGIS: reads spatial data
- Web application → Cart queries: manages cart
- Cart queries → API client: calls cart API
- API client → Cart API: calls API
- Cart API → Cart rules: delegates
- Cart rules → PostgreSQL and PostGIS: reads and writes
- Web application → Order queries: tracks orders
- Order queries → API client: calls order API
- API client → Checkout and orders: submits checkout
- Checkout and orders → PostgreSQL and PostGIS: creates orders
- Checkout and orders → Order lifecycle: checks transitions
- Authentication API → Authentication: delegates
- Authentication API → Cart rules: transfers guest cart
- Authentication → PostgreSQL and PostGIS: reads and writes
- Geocoding service → Geocoding providers: geocodes with
- Geocoding service → PostgreSQL and PostGIS: reads location data
- Store management → PostgreSQL and PostGIS: manages stores
- Inventory management → PostgreSQL and PostGIS: manages inventory
- Verified reviews → PostgreSQL and PostGIS: reads and writes
- Analytics → PostgreSQL and PostGIS: queries metrics
- Platform administration → PostgreSQL and PostGIS: queries platform data