LocalStore Platform - Contracts

📦 Shared types and contracts for LocalStore Platform - TypeScript definitions, GraphQL schemas, and Protobuf specs shared across all repos. Published as @localstore/types npm package for contract-driven development.

Overview

This repository contains the shared type definitions and contracts used across all LocalStore Platform services. It serves as the single source of truth for API interfaces, data models, and communication protocols.

Platform: Multi-tenant SaaS for Vietnamese small businesses (restaurants, street vendors)

Primary Market: Vietnam (vi-VN locale, VND currency)

📋 Table of Contents

• [Features](# ✨ features)
• [Tech Stack](# 🛠 tech-stack)
• [Getting Started](# 🚀 getting-started)
• [Usage](# 📦 usage)
• [Development](# 🔧 development)
• [Contract Change Process](# 📜 contract-change-process)
• [Specifications](# 📚 specifications)
• [Contributing](# 🤝 contributing)
• [License](# 📄 license)

✨ Features

• TypeScript Type Definitions: Strongly-typed interfaces for all API contracts
• GraphQL Schema: Shared GraphQL type definitions and schema files
• Protobuf Definitions: Protocol buffer messages for inter-service communication
• Vietnamese Localization: Built-in support for vi-VN locale and VND currency
• Multi-Tenant Support: Types designed for multi-tenant architecture
• Semantic Versioning: Strict semver with contract change process
• NPM Package: Published as @localstore/types for easy consumption

🛠 Tech Stack

• Language: TypeScript 5.x
• Schema Tools:
  • GraphQL Code Generator
  • Protobuf Compiler (protoc)
• Build Tools: TypeScript Compiler (tsc)
• Testing: Jest with TypeScript support
• Package Manager: npm

🚀 Getting Started

Prerequisites

• Node.js 20.x or higher
• npm 10.x or higher

Installation

Install the package in your project:

npm install @localstore/types

Basic Usage

import { ProductDTO, CreateOrderRequest, OrderStatus } from '@localstore/types';

// Use strongly-typed contracts in your code
const product: ProductDTO = {
  id: 'prod_123',
  tenantId: 'tenant_456',
  name: 'Cà phê sữa đá',
  priceVnd: 25000,
  createdAt: new Date().toISOString()
};

// Type-safe API requests
const orderRequest: CreateOrderRequest = {
  tenantId: 'tenant_456',
  items: [
    { productId: 'prod_123', quantity: 2 }
  ],
  totalVnd: 50000
};

📦 Usage

TypeScript Types

All type definitions are exported from the main package:

// API DTOs
import { ProductDTO, OrderDTO, CustomerDTO } from '@localstore/types';

// Request/Response types
import { CreateProductRequest, UpdateOrderRequest } from '@localstore/types';

// Domain enums and constants
import { OrderStatus, PaymentMethod, UserRole } from '@localstore/types';

GraphQL Schema

GraphQL schema files are available for code generation:

# Reference in your codegen.yml
schema: './node_modules/@localstore/types/graphql/schema.graphql'

Protobuf Definitions

Protobuf files for gRPC services:

# Reference in your proto compilation
protoc --proto_path=./node_modules/@localstore/types/proto

🔧 Development

Local Development Setup

1. Clone the repository:

   git clone https://github.com/localstore-platform/contracts.git
   cd contracts

2. Install dependencies:

   npm install

3. Build the project:

   npm run build

4. Run tests:

   npm test

See Development Guide for detailed setup instructions.

Project Structure

contracts/
├── types/              # TypeScript type definitions
│   ├── api/           # REST API DTOs
│   ├── graphql/       # GraphQL-specific types
│   └── domain/        # Domain models
├── graphql/           # GraphQL schema files
├── proto/             # Protobuf definitions
├── dist/              # Compiled output (generated)
├── docs/              # Documentation
└── tests/             # Test files

📝 Contract Change Process

This repository follows a strict contract change process to maintain stability across all consuming services.

Version Bumping

• Major (x.0.0): Breaking changes (removed/renamed fields, changed types)
• Minor (0.x.0): New features (new types, optional fields)
• Patch (0.0.x): Bug fixes (correcting spec mismatches)

Making Changes

1. Reference the specification: All changes must align with the specs repository
2. Assess impact: Determine if the change is breaking
3. Update documentation: Update CHANGELOG.md and migration guides
4. Coordinate releases: For breaking changes, coordinate with all consumers
5. Follow PR template: Use the provided pull request template

See the Contract Change Process for full details.

📚 Specifications

This repository implements type definitions based on specifications from the LocalStore Platform Specs Repository.

**Spec Version: master (latest)

Key Specification Documents

• API Specification - REST API contracts
• GraphQL Schema - GraphQL type system
• Database Schema - Data models and enums
• Contract Change Process - Change management

See docs/SPEC_LINKS.md for a complete list of relevant specifications.

🤝 Contributing

We welcome contributions! Please follow these guidelines:

1. Check specifications first: All changes must align with the specs repository
2. Use issue templates: Bug reports and feature requests have dedicated templates
3. Follow PR template: The pull request template ensures all required information is provided
4. Write tests: All new types should have unit tests
5. Update documentation: Keep README, CHANGELOG, and inline docs up to date

Development Workflow

1. Create a feature branch: git checkout -b feature/my-new-type
2. Make changes following the Development Guide
3. Add tests and ensure all tests pass
4. Submit a pull request using the PR template
5. Address review feedback

All changes require approval from code owners before merging.

📄 License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) - see the LICENSE file for details.

🔗 Related Repositories

• Specifications - Source of truth for all platform specifications
• Backend - Backend API implementation
• Web Dashboard - Web-based management interface

📞 Support

• Issues: Use GitHub Issues with appropriate templates
• Discussions: Join team discussions for general questions
• Specifications: Check the specs repository for detailed requirements

Vietnamese Localization: All types are designed with Vietnamese small businesses in mind, using vi-VN locale and VND currency by default.

Multi-Tenant Architecture: All contracts support multi-tenant isolation and tenant-scoped data access.