# neo7337/bite-express architecture

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

- Interactive diagram: https://gitdiagram.com/neo7337/bite-express
- Repository: https://github.com/neo7337/bite-express

## Overview

BiteExpress is a multi-tenant restaurant discovery API backed by MongoDB. A client lists, retrieves, creates, or naturally searches restaurants; REST handlers validate and translate requests, the service applies tenant scope and merges search intent, and a cached repository serves the MongoDB query. A separate seed command cleans and upserts CSV data. The graph includes README-documented capabilities such as geo sorting, health/readiness, and idempotent seeding; some internal implementation links are omitted where sampled source does not establish the call.

Main entry points: [`internal/api/rest/handler/restaurants_handler.go`](https://github.com/neo7337/bite-express/blob/main/internal/api/rest/handler/restaurants_handler.go) (Restaurant handlers), [`internal/repository/connections/conn_manager.go`](https://github.com/neo7337/bite-express/blob/main/internal/repository/connections/conn_manager.go) (Connection manager), [`internal/api/rest/router/router.go`](https://github.com/neo7337/bite-express/blob/main/internal/api/rest/router/router.go) (Route dispatch), [`internal/service/restaurants_svc.go`](https://github.com/neo7337/bite-express/blob/main/internal/service/restaurants_svc.go) (Restaurant service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["REST API"]
  node_restserver["REST server<br/>[rest.go]"]
  node_router["Route dispatch<br/>[router.go]"]
  node_handlers["Restaurant handlers"]
  node_params["Query parameters<br/>[params.go]"]
  node_validation["Request validation<br/>[validate.go]"]
  node_dto["API DTO mapping<br/>[dto.go]"]
end

subgraph group_search["Search"]
  node_service["Restaurant service<br/>[restaurants_svc.go]"]
  node_nlq["NLQ interpretation"]
end

subgraph group_data["Data access"]
  node_connections["Connection manager<br/>[conn_manager.go]"]
  node_cachewrap["Cached repository<br/>[restaurants.go]"]
  node_cache["Memory cache<br/>[cache.go]"]
  node_repoiface["Repository contract"]
  node_mongoimpl["Mongo repository"]
  node_pipeline["Query aggregation<br/>[pipeline.go]"]
  node_mongoconnection["Mongo connection<br/>[repository.go]"]
  node_mongodb[("MongoDB")]
end

subgraph group_operations["Runtime and ingestion"]
  node_server["Server entry<br/>[server.go]"]
  node_app["App lifecycle<br/>[app.go]"]
  node_config["Configuration<br/>[config.go]"]
  node_seed["CSV seeding<br/>[main.go]"]
  node_clean["Seed cleanup<br/>[clean.go]"]
end

node_client(("API client"))

node_client -->|"sends requests"| node_restserver
node_server -->|"loads settings"| node_config
node_server -->|"starts"| node_app
node_app -->|"registers lifecycle"| node_connections
node_app -->|"starts after connections"| node_restserver
node_restserver -->|"configures routes"| node_router
node_router -->|"dispatches requests"| node_handlers
node_router -->|"constructs service"| node_service
node_router -->|"checks readiness"| node_connections
node_handlers -->|"parses filters"| node_params
node_handlers -.->|"validates create"| node_validation
node_handlers -->|"calls operations"| node_service
node_handlers -.->|"maps responses"| node_dto
node_service -->|"interprets query"| node_nlq
node_service -->|"reads and writes"| node_repoiface
node_connections -->|"opens connection"| node_mongoconnection
node_connections -->|"registers repository"| node_mongoimpl
node_connections -->|"wraps when enabled"| node_cachewrap
node_cachewrap -->|"uses providers"| node_cache
node_cachewrap -->|"delegates cache misses"| node_mongoimpl
node_mongoimpl -.->|"builds list aggregation"| node_pipeline
node_mongoconnection -->|"connects and pings"| node_mongodb
node_mongoimpl -.->|"queries restaurants"| node_mongodb
node_clean -->|"cleans input"| node_seed
node_seed -->|"upserts records"| node_mongodb

click node_server "https://github.com/neo7337/bite-express/blob/main/cmd/server/server.go"
click node_app "https://github.com/neo7337/bite-express/blob/main/internal/app/app.go"
click node_config "https://github.com/neo7337/bite-express/blob/main/internal/config/config.go"
click node_restserver "https://github.com/neo7337/bite-express/blob/main/internal/api/rest/rest.go"
click node_router "https://github.com/neo7337/bite-express/blob/main/internal/api/rest/router/router.go"
click node_handlers "https://github.com/neo7337/bite-express/blob/main/internal/api/rest/handler/restaurants_handler.go"
click node_params "https://github.com/neo7337/bite-express/blob/main/internal/api/rest/handler/params.go"
click node_validation "https://github.com/neo7337/bite-express/blob/main/internal/api/rest/handler/validate.go"
click node_dto "https://github.com/neo7337/bite-express/blob/main/internal/api/rest/handler/dto.go"
click node_service "https://github.com/neo7337/bite-express/blob/main/internal/service/restaurants_svc.go"
click node_nlq "https://github.com/neo7337/bite-express/tree/main/internal/search/nlq"
click node_seed "https://github.com/neo7337/bite-express/blob/main/cmd/seed/main.go"
click node_clean "https://github.com/neo7337/bite-express/blob/main/cmd/seed/clean.go"
click node_connections "https://github.com/neo7337/bite-express/blob/main/internal/repository/connections/conn_manager.go"
click node_cachewrap "https://github.com/neo7337/bite-express/blob/main/internal/repository/cached/restaurants.go"
click node_cache "https://github.com/neo7337/bite-express/blob/main/internal/cache/cache.go"
click node_repoiface "https://github.com/neo7337/bite-express/blob/main/internal/repository/restaurants_repo.go"
click node_mongoimpl "https://github.com/neo7337/bite-express/blob/main/internal/repository/mongodb/restaurants_repo_impl.go"
click node_pipeline "https://github.com/neo7337/bite-express/blob/main/internal/repository/mongodb/pipeline.go"
click node_mongoconnection "https://github.com/neo7337/bite-express/blob/main/internal/repository/mongodb/repository.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_restserver,node_router,node_handlers,node_params,node_validation,node_dto,node_client toneBlue
class node_service,node_nlq toneAmber
class node_connections,node_cachewrap,node_cache,node_repoiface,node_mongoimpl,node_pipeline,node_mongoconnection,node_mongodb toneMint
class node_server,node_app,node_config,node_seed,node_clean toneRose
```

## Components

### REST API

- [REST server](https://github.com/neo7337/bite-express/blob/main/internal/api/rest/rest.go): `internal/api/rest/rest.go`
- [Route dispatch](https://github.com/neo7337/bite-express/blob/main/internal/api/rest/router/router.go): `internal/api/rest/router/router.go`
- [Restaurant handlers](https://github.com/neo7337/bite-express/blob/main/internal/api/rest/handler/restaurants_handler.go): `internal/api/rest/handler/restaurants_handler.go`
- [Query parameters](https://github.com/neo7337/bite-express/blob/main/internal/api/rest/handler/params.go): `internal/api/rest/handler/params.go`
- [Request validation](https://github.com/neo7337/bite-express/blob/main/internal/api/rest/handler/validate.go): `internal/api/rest/handler/validate.go`
- [API DTO mapping](https://github.com/neo7337/bite-express/blob/main/internal/api/rest/handler/dto.go): `internal/api/rest/handler/dto.go`

### Search

- [Restaurant service](https://github.com/neo7337/bite-express/blob/main/internal/service/restaurants_svc.go): `internal/service/restaurants_svc.go`
- [NLQ interpretation](https://github.com/neo7337/bite-express/tree/main/internal/search/nlq): `internal/search/nlq`

### Data access

- [Connection manager](https://github.com/neo7337/bite-express/blob/main/internal/repository/connections/conn_manager.go): `internal/repository/connections/conn_manager.go`
- [Cached repository](https://github.com/neo7337/bite-express/blob/main/internal/repository/cached/restaurants.go): `internal/repository/cached/restaurants.go`
- [Memory cache](https://github.com/neo7337/bite-express/blob/main/internal/cache/cache.go): `internal/cache/cache.go`
- [Repository contract](https://github.com/neo7337/bite-express/blob/main/internal/repository/restaurants_repo.go): `internal/repository/restaurants_repo.go`
- [Mongo repository](https://github.com/neo7337/bite-express/blob/main/internal/repository/mongodb/restaurants_repo_impl.go): `internal/repository/mongodb/restaurants_repo_impl.go`
- [Query aggregation](https://github.com/neo7337/bite-express/blob/main/internal/repository/mongodb/pipeline.go): `internal/repository/mongodb/pipeline.go`
- [Mongo connection](https://github.com/neo7337/bite-express/blob/main/internal/repository/mongodb/repository.go): `internal/repository/mongodb/repository.go`
- **MongoDB**

### Runtime and ingestion

- [Server entry](https://github.com/neo7337/bite-express/blob/main/cmd/server/server.go): `cmd/server/server.go`
- [App lifecycle](https://github.com/neo7337/bite-express/blob/main/internal/app/app.go): `internal/app/app.go`
- [Configuration](https://github.com/neo7337/bite-express/blob/main/internal/config/config.go): `internal/config/config.go`
- [CSV seeding](https://github.com/neo7337/bite-express/blob/main/cmd/seed/main.go): `cmd/seed/main.go`
- [Seed cleanup](https://github.com/neo7337/bite-express/blob/main/cmd/seed/clean.go): `cmd/seed/clean.go`

### Other components

- **API client**

## Connections

- API client → REST server: sends requests (evidence: `README.md`)
- Server entry → Configuration: loads settings (evidence: `cmd/server/server.go`)
- Server entry → App lifecycle: starts (evidence: `cmd/server/server.go`)
- App lifecycle → Connection manager: registers lifecycle (evidence: `internal/app/app.go`)
- App lifecycle → REST server: starts after connections (evidence: `internal/app/app.go`)
- REST server → Route dispatch: configures routes (evidence: `internal/api/rest/rest.go`)
- Route dispatch → Restaurant handlers: dispatches requests (evidence: `internal/api/rest/router/router.go`)
- Route dispatch → Restaurant service: constructs service (evidence: `internal/api/rest/router/router.go`)
- Route dispatch → Connection manager: checks readiness (evidence: `internal/api/rest/router/router.go`)
- Restaurant handlers → Query parameters: parses filters (evidence: `internal/api/rest/handler/restaurants_handler.go`)
- Restaurant handlers → Request validation: validates create
- Restaurant handlers → Restaurant service: calls operations (evidence: `internal/api/rest/handler/restaurants_handler.go`)
- Restaurant handlers → API DTO mapping: maps responses
- Restaurant service → NLQ interpretation: interprets query (evidence: `internal/service/restaurants_svc.go`)
- Restaurant service → Repository contract: reads and writes (evidence: `internal/service/restaurants_svc.go`)
- Connection manager → Mongo connection: opens connection (evidence: `internal/repository/connections/conn_manager.go`)
- Connection manager → Mongo repository: registers repository (evidence: `internal/repository/connections/conn_manager.go`)
- Connection manager → Cached repository: wraps when enabled (evidence: `internal/repository/connections/conn_manager.go`)
- Cached repository → Memory cache: uses providers (evidence: `internal/repository/cached/restaurants.go`)
- Cached repository → Mongo repository: delegates cache misses (evidence: `internal/repository/cached/restaurants.go`)
- Mongo repository → Query aggregation: builds list aggregation
- Mongo connection → MongoDB: connects and pings (evidence: `internal/repository/mongodb/repository.go`)
- Mongo repository → MongoDB: queries restaurants
- Seed cleanup → CSV seeding: cleans input (evidence: `cmd/seed/clean.go`)
- CSV seeding → MongoDB: upserts records (evidence: `README.md`)
