How mardan-shah/haizra-backend works
1. This is a Bun-based backend service, not a full-stack app. The runtime entrypoint is src/index.ts, and the README indicates the server is started directly with Bun.
2. The code is organized around a resource-oriented API layer in src/api/. Each file corresponds to a domain area: users, products, orders, auctions, reviews, and storefronts. These modules are the main request-handling boundary.
3. The API layer is backed by a database access layer in src/db/. src/db/db.ts likely centralizes the database connection, while src/db/migrate.ts handles schema migrations or migration execution.
4. Database structure is defined with Drizzle ORM under src/db/schema/. The schema is split by business concept: users, addresses, products, orders, auctions, ratings, and transactions, plus relations.ts for table relationships and index.ts as the schema export surface.
5. The repository includes committed SQL migrations in the top-level drizzle/ directory and matching snapshots in drizzle/meta/. This means schema evolution is managed through versioned migration artifacts rather than ad hoc runtime DDL.
6. The main data flow is: incoming request → resource module in src/api/ → shared DB layer → Drizzle schema/migrations-backed PostgreSQL-style tables. The architecture is centered on persistence-first domain modules rather than in-memory services.
7. Authentication-related logic appears isolated in src/utils/auth.ts. That suggests auth is treated as a cross-cutting utility rather than being embedded inside each API resource.
8. There are two utility scripts at the repo root: reset-db.ts for rebuilding or clearing the database state, and debug-schema.ts for inspecting schema behavior. These are operational/support tools, not part of the request path.
9. Configuration and environment management are explicit: .env.example documents required runtime settings, drizzle.config.ts wires Drizzle tooling, bunfig.toml configures the Bun runtime, and nixpacks.toml suggests deployment/build-time packaging support.
10. The most important architectural boundary is between domain API modules and persistence. There is no evidence of separate frontend, queue worker, or microservice boundaries; this repo is a single-process backend exposing several business domains over a shared database.
Main entry points: schema/index.ts Schema export · src/index.ts Server entry · db.ts DB layer · migrate.ts Migrator
Components 25
Runtime
Bun entrypoint and process startup
- Server entry · Starts the backend process with Bun
src/index.ts
API
Resource-oriented request handlers
- Users API · Handles user-facing requests and domain actions
src/api/users.ts - Products API · Handles product-related requests
src/api/products.ts - Orders API · Handles order lifecycle requests
src/api/orders.ts - Auctions API · Handles auction workflow requests
src/api/auctions.ts - Reviews API · Handles review and rating requests
src/api/reviews.ts - Storefronts API · Handles storefront-related requests
src/api/storefronts.ts
Persistence
Shared database access, schema, and migrations
- DB layer · Shared database connection and query access
src/db/db.ts - Migrator · Runs or coordinates database migrations
src/db/migrate.ts - Schema export · Central export surface for Drizzle schema modules
src/db/schema/index.ts - Users table · User identity and account data
src/db/schema/users.ts - Addresses · Address records used by domain tables
src/db/schema/addresses.ts - Products table · Product catalog persistence
src/db/schema/products.ts - Orders table · Order persistence and status data
src/db/schema/orders.ts - Auctions table · Auction persistence and lifecycle data
src/db/schema/auctions.ts - Ratings table · Review and rating persistence
src/db/schema/ratings.ts - Transactions · Transactional and payment-related persistence
src/db/schema/transactions.ts - Relations · Defines table relationships for Drizzle
src/db/schema/relations.ts - Migrations · Versioned SQL migration files tracked in drizzle/
drizzle
Ops
Support scripts and runtime configuration
- Schema debug · Inspects schema behavior during development
debug-schema.ts - Reset DB · Clears or rebuilds database state
reset-db.ts - Env sample · Documents required runtime environment variables
.env.example - Bun config · Configures Bun behavior for the project
bunfig.toml - Drizzle config · Configures Drizzle ORM tooling and migration paths
drizzle.config.ts - Nixpacks · Build and deployment packaging configuration
nixpacks.toml
Connections 29
- Server entry → Users API: routes to · Entrypoint loads resource handlers
- Server entry → Products API: routes to · Entrypoint loads resource handlers
- Server entry → Orders API: routes to · Entrypoint loads resource handlers
- Server entry → Auctions API: routes to · Entrypoint loads resource handlers
- Server entry → Reviews API: routes to · Entrypoint loads resource handlers
- Server entry → Storefronts API: routes to · Entrypoint loads resource handlers
- Users API → DB layer: queries · User requests read and write through shared DB access
- Products API → DB layer: queries · Product requests read and write through shared DB access
- Orders API → DB layer: queries · Order requests read and write through shared DB access
- Auctions API → DB layer: queries · Auction requests read and write through shared DB access
- Reviews API → DB layer: queries · Review requests read and write through shared DB access
- Storefronts API → DB layer: queries · Storefront requests read and write through shared DB access
- DB layer → Schema export: uses schema · Database access is shaped by the shared schema surface
- Schema export → Users table: exports · Aggregates schema modules
- Schema export → Addresses: exports · Aggregates schema modules
- Schema export → Products table: exports · Aggregates schema modules
- Schema export → Orders table: exports · Aggregates schema modules
- Schema export → Auctions table: exports · Aggregates schema modules
- Schema export → Ratings table: exports · Aggregates schema modules
- Schema export → Transactions: exports · Aggregates schema modules
- Schema export → Relations: exports · Aggregates schema modules
- Migrator → Migrations: applies · Migration runner consumes committed SQL history
- Migrator → Schema export: aligns with · Migration execution is kept in sync with schema definitions
- Schema debug → Schema export: inspects · Development tool examines schema behavior
- Reset DB → DB layer: operates on · Reset script uses shared database access
- Drizzle config → Migrations: targets · Tooling points at migration artifacts
- Bun config → Server entry: configures · Runtime configuration supports Bun startup
- Env sample → Server entry: documents · Sample environment settings for startup
- Nixpacks → Server entry: packages · Deployment config supports running the server