# Restaurant POS Dashboard API

A RESTful API for managing restaurant sales data from POS systems with OAuth 2.0 authentication and role-based access control.

## Features

- **Hierarchical Restaurant Management**: Group > Brand > Outlet structure
- **OAuth 2.0 Authentication**: Secure API access with multiple grant types
- **Role-Based Access Control**: Fine-grained permissions system
- **POS Integration**: Sync sales data from POS systems
- **PostgreSQL Database**: With Repository pattern for database abstraction
- **TypeScript**: Full type support for better developer experience

## Project Structure

The project follows a clean architecture approach with separation of concerns:

- **API**: Controllers, routes, validators, and middlewares
- **Domain**: Business logic, interfaces, and models
- **Infrastructure**: Database, repositories, and external services
- **Utils**: Helper functions and error handling

## Prerequisites

- Node.js (>= 18.x)
- PostgreSQL (>= 14.x)
- npm or yarn

## Installation

1. Clone the repository:
   ```
   git clone https://github.com/yourusername/restaurant-pos-dashboard.git
   cd restaurant-pos-dashboard
   ```

2. Install dependencies:
   ```
   npm install
   ```

3. Create a `.env` file based on `.env.example`:
   ```
   cp .env.example .env
   ```

4. Update the `.env` file with your configuration settings.

5. Run database migrations:
   ```
   npm run migrate
   ```

6. Seed the database with initial data:
   ```
   npm run seed
   ```

## Development

Start the development server with hot-reloading:

```
npm run dev
```

The server will be running at http://localhost:3000 (or the port specified in your .env file).

## API Endpoints

### Authentication

- `POST /api/v1/oauth/token` - OAuth 2.0 token endpoint

### Restaurants

- `GET /api/v1/restaurants/groups` - Get all restaurant groups
- `GET /api/v1/restaurants/groups/:id` - Get a specific restaurant group
- `POST /api/v1/restaurants/groups` - Create a new restaurant group
- `PUT /api/v1/restaurants/groups/:id` - Update a restaurant group
- `DELETE /api/v1/restaurants/groups/:id` - Delete a restaurant group
- `GET /api/v1/restaurants/groups/:id/hierarchy` - Get the full hierarchy for a group

### Brands

- `GET /api/v1/restaurants/groups/:groupId/brands` - Get all brands for a group
- `POST /api/v1/restaurants/groups/:groupId/brands` - Create a new brand
- `PUT /api/v1/restaurants/brands/:id` - Update a brand
- `DELETE /api/v1/restaurants/brands/:id` - Delete a brand

### Outlets

- `GET /api/v1/restaurants/brands/:brandId/outlets` - Get all outlets for a brand
- `POST /api/v1/restaurants/brands/:brandId/outlets` - Create a new outlet
- `PUT /api/v1/restaurants/outlets/:id` - Update an outlet
- `DELETE /api/v1/restaurants/outlets/:id` - Delete an outlet
- `GET /api/v1/restaurants/outlets/pos/:posId` - Find an outlet by POS ID

### Data Sync

- `POST /api/v1/sync/sales` - Sync sales data from POS
- `GET /api/v1/sync/status/:syncId` - Check the status of a sync
- `GET /api/v1/sync/history/:posId` - Get sync history for a POS

## Database Schema

### Main Tables

- `restaurant_groups` - Top-level restaurant groups
- `restaurant_brands` - Brands belonging to groups
- `restaurant_outlets` - Physical restaurant locations
- `users` - System users with roles and permissions
- `user_restaurant_access` - User access to specific restaurants
- `sales_data` - Sales data synced from POS systems

### OAuth Tables

- `oauth_clients` - OAuth client applications
- `oauth_tokens` - Access and refresh tokens
- `oauth_auth_codes` - Authorization codes for OAuth flow

## Authentication & Authorization

The API uses OAuth 2.0 for authentication with the following grant types:

- `password` - For user authentication
- `client_credentials` - For server-to-server API access
- `refresh_token` - For obtaining new access tokens
- `authorization_code` - For web application flows

Role-based access control (RBAC) is implemented with the following roles:

- `admin` - Full system access
- `manager` - Restaurant management access
- `staff` - Limited restaurant access
- `api` - API-only access for POS integration

## Error Handling

The API uses standardized error responses with the following format:

```json
{
  "status": "error",
  "message": "Error message",
  "code": "ERROR_CODE",
  "errors": []
}
```

## Testing

Run tests with:

```
npm test
```

## Production Build

Build the production version:

```
npm run build
```

Start the production server:

```
npm start
```

## License

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