# alif10151/simple_listing_website architecture

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

- Interactive diagram: https://gitdiagram.com/alif10151/simple_listing_website
- Repository: https://github.com/alif10151/simple_listing_website

## Overview

1. **High-level shape**
   - This repo is a two-part full-stack application: a React single-page frontend in `client/` and a Go backend in `backend/`.
   - The README describes a MERN stack, but the actual backend tree is Go + SQL, not Node/Express + MongoDB. That mismatch is important for an architecture diagram.

2. **Frontend boundary**
   - `client/` is a classic React app with page components, reusable UI components, a small API service layer, and CSS-based styling.
   - `src/pages` contains route-level screens like `HomePage`, `SingleProductPage`, and `NotFoundPage`.
   - `src/components` contains the product UI primitives: list, card, and add/edit form.
   - `src/services/api.js` is the main boundary to the backend; it centralizes HTTP calls rather than letting components talk directly to the server.

3. **Frontend data flow**
   - User interactions happen in page/components, which call the API service.
   - The UI renders product collections, single-product details, and add/edit forms, then refreshes state from server responses after CRUD operations.
   - Routing is handled on the client side, so the backend is primarily an API provider rather than a page renderer.

4. **Backend entrypoint and composition**
   - The backend starts from `backend/main.go` and `backend/cmd/serve.go`, which likely bootstrap configuration, database access, and the HTTP server.
   - `backend/config/config.go` reads runtime configuration, including environment-based settings.
   - `backend/rest/server.go` is the HTTP composition root: it wires routes, middleware, and handlers together.

5. **REST API layer**
   - The API is organized by resource under `backend/rest/handlers/product` and `backend/rest/handlers/user`.
   - Product handlers implement create, read, update, delete, and collection retrieval.
   - User handlers implement user creation and login.
   - Each resource has its own `handler.go`, `routes.go`, and `port.go`, which suggests a clean separation between HTTP concerns and business logic.

6. **Middleware and cross-cutting concerns**
   - `backend/rest/middlewares` contains CORS handling, preflight handling, structured logging, and JWT authentication.
   - `authenticate_jwt.go` is the key security boundary for protected endpoints.
   - `manager.go` and `middleware.go` indicate middleware composition is centralized instead of scattered across handlers.

7. **Business/service layer**
   - The domain logic is split into `backend/product` and `backend/user`.
   - These packages expose `service.go` and `port.go`, which suggests use of interfaces to decouple services from handlers and persistence.
   - This layer is the main place where application rules would live, while handlers remain thin.

8. **Domain model**
   - `backend/domain/product.go` and `backend/domain/user.go` define the core entities used across the backend.
   - These types are the shared contract between HTTP, service, and repository layers.
   - The architecture is centered on these domain objects rather than on framework-specific models.

9. **Persistence layer**
   - `backend/repo/product.go` and `backend/repo/user.go` implement data access.
   - `backend/infrastructure/db/connections.go` and `migrate.go` manage database connectivity and schema migration support.
   - The presence of `backend/migrations/*.up.sql` and `*.down.sql`, plus `backend/db_queries/*.sql`, indicates raw SQL with explicit schema/version control rather than an ORM.

10. **Database boundary**
   - The backend persists products and users in a relational-style database schema.
   - Migrations create and evolve the `users` and `products` tables.
   - The `db_queries` folder suggests some operations are defined as standalone SQL files, which keeps SQL close to the repo and makes query behavior explicit.

11. **Authentication flow**
   - User login goes through the user handler, then the user service/repo, and on success a JWT is created in `backend/utility/create_jwt.go`.
   - Authenticated requests are then validated by the JWT middleware before reaching protected handlers.
   - This makes authentication a cross-cutting concern rather than part of product logic.

12. **Shared utilities**
   - `backend/utility/send_data.go` likely standardizes JSON/API responses.
   - Centralized helpers like this reduce duplication across handlers and make response shape consistent.

13. **End-to-end request path**
   - A typical product request flows: React component → `client/src/services/api.js` → Go REST server → middleware → product handler → service → repository → DB → back through the same layers to the UI.
   - A login request follows the same path, but returns a JWT that is then used on subsequent protected calls.

14. **What to draw in the architecture diagram**
   - Show two top-level subsystems: React frontend and Go API backend.
   - Inside the backend, show four layers: REST handlers/middleware, service layer, repository layer, and DB/migrations.
   - Show JWT-based auth and CORS/logging as cross-cutting middleware.
   - Show the frontend communicating only through the API service layer, not directly with the database or backend internals.

Main entry points: [`backend/rest/server.go`](https://github.com/alif10151/simple_listing_website/blob/main/backend/rest/server.go) (REST server), [`backend/user/service.go`](https://github.com/alif10151/simple_listing_website/blob/main/backend/user/service.go) (User service), [`backend/infrastructure/db`](https://github.com/alif10151/simple_listing_website/tree/main/backend/infrastructure/db) (DB layer), [`client/src/pages`](https://github.com/alif10151/simple_listing_website/tree/main/client/src/pages) (Pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_client_app["App<br/>React shell<br/>[App.js]"]
  node_client_pages["Pages<br/>route screens"]
  node_client_components["Components<br/>UI widgets"]
  node_client_api["API service<br/>HTTP client<br/>[api.js]"]
end

subgraph group_backend["Backend"]
  node_backend_main["Main<br/>bootstrap<br/>[main.go]"]
  node_backend_config["Config<br/>[config.go]"]
  node_backend_server["REST server<br/>composition root<br/>[server.go]"]
  node_backend_mw["Middleware<br/>cross-cutting<br/>[manager.go]"]
  node_backend_product_handlers["Product API<br/>REST handlers"]
  node_backend_user_handlers["User API<br/>REST handlers"]
  node_backend_product_service["Product service<br/>business logic<br/>[service.go]"]
  node_backend_user_service["User service<br/>business logic<br/>[service.go]"]
  node_backend_product_repo["Product repo<br/>SQL repository<br/>[product.go]"]
  node_backend_user_repo["User repo<br/>SQL repository<br/>[user.go]"]
  node_backend_domain["Domain models<br/>entities"]
  node_backend_jwt["JWT helper<br/>token utility<br/>[create_jwt.go]"]
  node_backend_send["Response helper<br/>[send_data.go]"]
end

subgraph group_data["Data"]
  node_backend_db[("DB layer<br/>database infra")]
  node_backend_migrations["Migrations<br/>schema versioning"]
  node_backend_queries["SQL queries<br/>raw SQL"]
end

node_client_app -->|"renders"| node_client_pages
node_client_pages -->|"uses"| node_client_components
node_client_components -->|"calls"| node_client_api
node_client_pages -->|"calls"| node_client_api
node_client_api -->|"HTTP"| node_backend_server
node_backend_main -->|"loads"| node_backend_config
node_backend_main -->|"starts"| node_backend_server
node_backend_server -->|"applies"| node_backend_mw
node_backend_server -->|"routes"| node_backend_product_handlers
node_backend_server -->|"routes"| node_backend_user_handlers
node_backend_mw -->|"auth"| node_backend_jwt
node_backend_product_handlers -->|"uses"| node_backend_product_service
node_backend_user_handlers -->|"uses"| node_backend_user_service
node_backend_product_service -->|"persists"| node_backend_product_repo
node_backend_user_service -->|"persists"| node_backend_user_repo
node_backend_product_service -->|"models"| node_backend_domain
node_backend_user_service -->|"models"| node_backend_domain
node_backend_product_repo -->|"connects"| node_backend_db
node_backend_user_repo -->|"connects"| node_backend_db
node_backend_db -->|"migrates"| node_backend_migrations
node_backend_db -->|"runs"| node_backend_queries
node_backend_user_service -->|"issues token"| node_backend_jwt
node_backend_product_handlers -->|"responds"| node_backend_send
node_backend_user_handlers -->|"responds"| node_backend_send

click node_client_app "https://github.com/alif10151/simple_listing_website/blob/main/client/src/App.js"
click node_client_pages "https://github.com/alif10151/simple_listing_website/tree/main/client/src/pages"
click node_client_components "https://github.com/alif10151/simple_listing_website/tree/main/client/src/components"
click node_client_api "https://github.com/alif10151/simple_listing_website/blob/main/client/src/services/api.js"
click node_backend_main "https://github.com/alif10151/simple_listing_website/blob/main/backend/main.go"
click node_backend_config "https://github.com/alif10151/simple_listing_website/blob/main/backend/config/config.go"
click node_backend_server "https://github.com/alif10151/simple_listing_website/blob/main/backend/rest/server.go"
click node_backend_mw "https://github.com/alif10151/simple_listing_website/blob/main/backend/rest/middlewares/manager.go"
click node_backend_product_handlers "https://github.com/alif10151/simple_listing_website/tree/main/backend/rest/handlers/product"
click node_backend_user_handlers "https://github.com/alif10151/simple_listing_website/tree/main/backend/rest/handlers/user"
click node_backend_product_service "https://github.com/alif10151/simple_listing_website/blob/main/backend/product/service.go"
click node_backend_user_service "https://github.com/alif10151/simple_listing_website/blob/main/backend/user/service.go"
click node_backend_product_repo "https://github.com/alif10151/simple_listing_website/blob/main/backend/repo/product.go"
click node_backend_user_repo "https://github.com/alif10151/simple_listing_website/blob/main/backend/repo/user.go"
click node_backend_domain "https://github.com/alif10151/simple_listing_website/tree/main/backend/domain"
click node_backend_db "https://github.com/alif10151/simple_listing_website/tree/main/backend/infrastructure/db"
click node_backend_migrations "https://github.com/alif10151/simple_listing_website/tree/main/backend/migrations"
click node_backend_queries "https://github.com/alif10151/simple_listing_website/tree/main/backend/db_queries"
click node_backend_jwt "https://github.com/alif10151/simple_listing_website/blob/main/backend/utility/create_jwt.go"
click node_backend_send "https://github.com/alif10151/simple_listing_website/blob/main/backend/utility/send_data.go"

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_client_app,node_client_pages,node_client_components,node_client_api toneBlue
class node_backend_main,node_backend_config,node_backend_server,node_backend_mw,node_backend_product_handlers,node_backend_user_handlers,node_backend_product_service,node_backend_user_service,node_backend_product_repo,node_backend_user_repo,node_backend_domain,node_backend_jwt,node_backend_send toneAmber
class node_backend_db,node_backend_migrations,node_backend_queries toneMint
```

## Components

### Frontend

React SPA and UI layer

- [App](https://github.com/alif10151/simple_listing_website/blob/main/client/src/App.js): React shell · Client-side router and app composition · `client/src/App.js`
- [Pages](https://github.com/alif10151/simple_listing_website/tree/main/client/src/pages): route screens · Home, single product, and not-found screens · `client/src/pages`
- [Components](https://github.com/alif10151/simple_listing_website/tree/main/client/src/components): UI widgets · Product list, card, and add/edit form · `client/src/components`
- [API service](https://github.com/alif10151/simple_listing_website/blob/main/client/src/services/api.js): HTTP client · Centralized calls to the backend API · `client/src/services/api.js`

### Backend

Go API and application logic

- [Main](https://github.com/alif10151/simple_listing_website/blob/main/backend/main.go): bootstrap · Program entrypoint and server startup · `backend/main.go`
- [Config](https://github.com/alif10151/simple_listing_website/blob/main/backend/config/config.go): runtime config · Environment and application settings · `backend/config/config.go`
- [REST server](https://github.com/alif10151/simple_listing_website/blob/main/backend/rest/server.go): composition root · Wires routes, middleware, and handlers · `backend/rest/server.go`
- [Middleware](https://github.com/alif10151/simple_listing_website/blob/main/backend/rest/middlewares/manager.go): cross-cutting · CORS, preflight, logging, and JWT auth · `backend/rest/middlewares/manager.go`
- [Product API](https://github.com/alif10151/simple_listing_website/tree/main/backend/rest/handlers/product): REST handlers · CRUD endpoints for products · `backend/rest/handlers/product`
- [User API](https://github.com/alif10151/simple_listing_website/tree/main/backend/rest/handlers/user): REST handlers · User creation and login endpoints · `backend/rest/handlers/user`
- [Product service](https://github.com/alif10151/simple_listing_website/blob/main/backend/product/service.go): business logic · Product rules and orchestration · `backend/product/service.go`
- [User service](https://github.com/alif10151/simple_listing_website/blob/main/backend/user/service.go): business logic · User rules and authentication flow · `backend/user/service.go`
- [Product repo](https://github.com/alif10151/simple_listing_website/blob/main/backend/repo/product.go): SQL repository · Product persistence access · `backend/repo/product.go`
- [User repo](https://github.com/alif10151/simple_listing_website/blob/main/backend/repo/user.go): SQL repository · User persistence access · `backend/repo/user.go`
- [Domain models](https://github.com/alif10151/simple_listing_website/tree/main/backend/domain): entities · Shared product and user types · `backend/domain`
- [JWT helper](https://github.com/alif10151/simple_listing_website/blob/main/backend/utility/create_jwt.go): token utility · Creates signed login tokens · `backend/utility/create_jwt.go`
- [Response helper](https://github.com/alif10151/simple_listing_website/blob/main/backend/utility/send_data.go): utility · Standardized API responses · `backend/utility/send_data.go`

### Data

SQL persistence and migrations

- [DB layer](https://github.com/alif10151/simple_listing_website/tree/main/backend/infrastructure/db): database infra · Connections and migration support · `backend/infrastructure/db`
- [Migrations](https://github.com/alif10151/simple_listing_website/tree/main/backend/migrations): schema versioning · SQL up/down migrations for tables · `backend/migrations`
- [SQL queries](https://github.com/alif10151/simple_listing_website/tree/main/backend/db_queries): raw SQL · Explicit query files for CRUD operations · `backend/db_queries`

## Connections

- App → Pages: renders · App composes route-level screens
- Pages → Components: uses · Pages assemble reusable product UI
- Components → API service: calls · User actions trigger API requests
- Pages → API service: calls · Screens fetch and refresh server data
- API service → REST server: HTTP · Frontend talks to the Go REST API
- Main → Config: loads · Startup reads runtime settings
- Main → REST server: starts · Entrypoint boots the HTTP server
- REST server → Middleware: applies · Request pipeline includes middleware
- REST server → Product API: routes · Product endpoints are mounted
- REST server → User API: routes · User endpoints are mounted
- Middleware → JWT helper: auth · Protected requests validate JWTs
- Product API → Product service: uses · Handlers delegate product logic
- User API → User service: uses · Handlers delegate user logic
- Product service → Product repo: persists · Product service reads and writes data
- User service → User repo: persists · User service reads and writes data
- Product service → Domain models: models · Service operates on shared entities
- User service → Domain models: models · Service operates on shared entities
- Product repo → DB layer: connects · Repository uses database connections
- User repo → DB layer: connects · Repository uses database connections
- DB layer → Migrations: migrates · Schema is managed through SQL migrations
- DB layer → SQL queries: runs · Queries are stored as explicit SQL files
- User service → JWT helper: issues token · Login returns a signed JWT
- Product API → Response helper: responds · Handlers format API responses
- User API → Response helper: responds · Handlers format API responses