Inventory Stock Tracker API

A backend TypeScript system designed using Spec-Driven Development to track product inventory, manage stock adjustments, and prevent stockouts through low-stock alerts. The system enforces strict type safety, ACID-compliant transactions, and modular boundaries.

Architecture Overview

The system follows a Modular Monolith architecture with a feature-based directory structure. The request pipeline enforces validation and authorization before reaching domain-specific business logic.

+---------------------+      +-------------------------+      +-----------------------+
|                     |      |                         |      |                       |
|   HTTP Client       | ---> |   Elysia Transport      | ---> |   Global Middleware   |
|   (Eden / Fetch)    |      |   Layer                 |      |   (Request ID, JWT)   |
|                     |      |                         |      |                       |
+---------------------+      +-------------------------+      +-----------------------+
                                        |                               |
                                        v                               v
                             +-------------------------+      +-----------------------+
                             |                         |      |                       |
                             |   TypeBox Validation    | ---> |   RBAC Guard          |
                             |   (Schema-First)        |      |   (requireRole)       |
                             |                         |      |                       |
                             +-------------------------+      +-----------------------+
                                        |
                                        v
                             +-------------------------+      +-----------------------+
                             |                         |      |                       |
                             |   Application Service   | ---> |   Drizzle ORM         |
                             |   (Business Logic)      |      |   (SQLite)            |
                             |                         |      |                       |
                             +-------------------------+      +-----------------------+
                                        |                               |
                                        v                               v
                             +-------------------------+      +-----------------------+
                             |                         |      |                       |
                             |   Standardized Response | <--- |   Winston Logger      |
                             |   (Success / Error)     |      |   (JSON / Structured) |
                             |                         |      |                       |
                             +-------------------------+      +-----------------------+

Tech Stack

• Runtime: Bun
• Framework: ElysiaJS
• Database and ORM: SQLite, Drizzle ORM
• Validation: TypeBox (@sinclair/typebox)
• Testing: Bun Test
• Linting and Formatting: Biome
• Documentation: TypeDoc, @elysia/openapi

Quick Start

Prerequisites

• Bun (version 1.x or later)
• Git

Installation and Configuration

1. Clone the repository:

   git clone https://github.com/ios-community/inventory-tracker-api.git
   cd inventory-tracker-api

2. Install dependencies:

   bun install

3. Copy the environment template and configure values:

   cp .env.example .env

   Ensure JWT_SECRET is changed in non-development environments.

4. Generate and apply database migrations, then seed initial data:

   bun run db:generate
   bun run db:migrate
   bun run db:seed

   The seed script creates one administrator user (username: admin, password: admin123) and three sample products.

5. Start the development server:

   bun run dev

   The server will be accessible at http://localhost:3000.

Available Scripts

Command	Description
bun run dev	Start development server with hot-reload.
bun run build	Compile project to JavaScript for production.
bun run start	Start production server from compiled output.
bun run typecheck	Execute strict TypeScript type checking.
bun run lint	Lint source code using Biome.
bun run format	Format source code using Biome.
bun run test	Execute unit and integration test suites.
bun run test:coverage	Execute tests with coverage reporting (target >= 80%).
bun run docs	Generate API documentation using TypeDoc.
bun run db:studio	Launch Drizzle Studio for database inspection.

API Documentation

Interactive OpenAPI documentation is available at: http://localhost:3000/openapi

Testing

Automated testing is enforced to ensure system reliability. Execute the following to verify coverage:

bun run test:coverage

Target coverage is a minimum of 80% overall, and 90% for critical modules such as stock-adjustments.

Contribution

Refer to CONTRIBUTING.md for guidelines on coding standards, Git workflow, and pull request requirements.

License

This project is licensed under the MIT License. See the LICENSE file for details.