# Codebase Understanding: acme-orders-api

*Generated by Codebase Onboarder agent | Investigation time: ~3 minutes*

---

## What This Project Does

REST API for managing customer orders with Stripe payment integration and email notifications. Node.js/Express with PostgreSQL via Sequelize ORM. *(confidence: 0.92)*

## Architecture

```
acme-orders-api/
├── src/
│   ├── routes/          # Express route handlers
│   ├── models/          # Sequelize ORM models
│   ├── middleware/       # Auth, rate limiting, validation
│   ├── services/        # Business logic (payment, email, inventory)
│   ├── jobs/            # Background workers (unknown queue system)
│   └── utils/           # Shared helpers
├── tests/               # Jest test suite
├── migrations/          # Sequelize migrations
└── docker-compose.yml   # PostgreSQL + Redis
```

### Component Confidence Map

| Component | Confidence | Evidence |
|-----------|-----------|----------|
| Route handlers (`/orders`, `/customers`, `/webhooks`) | 0.95 | Read all 6 route files, clear RESTful patterns |
| Sequelize models (Order, Customer, Product, LineItem) | 0.90 | Read model definitions, verified associations |
| Auth middleware (JWT + API key) | 0.85 | Read middleware, traced token validation flow |
| Stripe integration | 0.70 | Read `services/payment.js` interface but `StripeService` uses a wrapper library I'm not familiar with |
| Email service | 0.75 | Uses Resend API. Read the service file but couldn't verify template rendering |
| Background jobs | 0.40 | Found `jobs/` directory with 3 files but couldn't determine the queue system — no BullMQ, no Agenda, no obvious queue dependency |
| Deployment | 0.30 | Found `docker-compose.yml` for local dev but no CI/CD config, no Dockerfile for production |

## Key Patterns Identified

1. **Repository pattern** for data access — models are never queried directly from routes, always through `services/` *(confidence: 0.9)*
2. **Webhook-driven architecture** for Stripe events — `routes/webhooks.js` handles `checkout.session.completed`, `payment_intent.failed`, `invoice.paid` *(confidence: 0.95)*
3. **Middleware chain**: `auth → rateLimit → validate → handler` on all protected routes *(confidence: 0.9)*
4. **Soft deletes** on Order and Customer models (`deletedAt` column, `paranoid: true` in Sequelize) *(confidence: 0.85)*

## What I Don't Know

- **Queue system for background jobs** — `jobs/orderFulfillment.js` exports a `process` function but I couldn't find what calls it. No queue library in `package.json`. Possibly using a custom implementation or the dependency is missing from the lock file.
- **Production deployment** — No Dockerfile, no CI/CD config, no deployment scripts. Either deployed manually or config lives outside this repo.
- **Rate limiting configuration** — `middleware/rateLimit.js` references `process.env.RATE_LIMIT_WINDOW` but no `.env.example` file exists showing expected environment variables.
- **How inventory is tracked** — `services/inventory.js` exists but imports from `@acme/inventory-sdk` which is a private package I can't inspect.

## Assumptions Made

| Assumption | Confidence | Domain |
|-----------|-----------|--------|
| Database is PostgreSQL | 0.95 | `docker-compose.yml` specifies `postgres:15` image |
| Redis is used for sessions or caching | 0.70 | In `docker-compose.yml` but no Redis import found in application code |
| Auth uses JWT | 0.90 | `jsonwebtoken` in `package.json`, `middleware/auth.js` calls `jwt.verify()` |
| API key auth is for service-to-service | 0.60 | `middleware/apiKeyAuth.js` exists separately from JWT auth — likely for webhooks or internal services |
| No WebSocket support | 0.55 | Didn't find `socket.io` or `ws`, but `@acme/inventory-sdk` might use it internally |

## Hypotheses Tested and Rejected

- **GraphQL support**: Searched for `apollo`, `graphql`, `type-defs` — none found. Pure REST.
- **Monorepo structure**: No `lerna.json`, no `workspaces` in `package.json`, no `packages/` directory. Single-package repo.
- **TypeScript**: All files are `.js`. No `tsconfig.json`. Considered JSDoc typing but no `@type` annotations found.

## Investigation Trail

### Artifacts Logged During Investigation

```
empirica finding-log --finding "Express app with 6 route files, Sequelize ORM, 4 models" --impact 0.6
empirica finding-log --finding "Webhook-driven Stripe integration handles 3 event types" --impact 0.7
empirica finding-log --finding "Soft deletes on Order and Customer (paranoid: true)" --impact 0.5
empirica unknown-log --unknown "Queue system for background jobs — process() exported but no caller found"
empirica unknown-log --unknown "Production deployment config missing from repo"
empirica unknown-log --unknown "Rate limiting env vars undocumented — no .env.example"
empirica assumption-log --assumption "Redis in docker-compose but unused in app code" --confidence 0.7 --domain infrastructure
empirica assumption-log --assumption "API key auth is for service-to-service calls" --confidence 0.6 --domain architecture
empirica deadend-log --approach "Searched for GraphQL support" --why-failed "No GraphQL dependencies or schema files found"
empirica deadend-log --approach "Looked for TypeScript config" --why-failed "Pure JavaScript, no type annotations"
```

### What a Second Investigation Would Focus On

1. Resolve the queue system unknown — check if `@acme/inventory-sdk` bundles a queue
2. Find deployment config — check if there's a separate infra repo
3. Verify Redis usage — might be in a dependency's internal config
4. Map all environment variables — grep for `process.env` across codebase

---

*This investigation took 14 tool calls (8 Read, 4 Grep, 2 Glob) and produced
4 findings, 3 unknowns, 2 assumptions, and 2 dead-ends.*
