farmcontrol-api/README.md

# FarmControl API

A comprehensive REST API for managing 3D printing farms, inventory, and production workflows. Built with Node.js, Express, and MongoDB, featuring authentication with Keycloak and comprehensive logging.

## 🚀 Features

- **Production Management**: Manage printers, jobs, G-code files, and filaments
- **Inventory Control**: Track part stocks, filament stocks, and stock events
- **User Management**: Role-based access control with admin, creator, and member roles
- **Audit Logging**: Comprehensive audit trails for all operations
- **Authentication**: Secure authentication using Keycloak
- **Real-time Monitoring**: Spotlight functionality for real-time system monitoring
- **Scheduled Operations**: Automated data reseeding and maintenance tasks

## 📋 Prerequisites

- Node.js (v16 or higher)
- MongoDB
- Keycloak server (for authentication)
- npm or yarn package manager

## 🛠️ Installation

1. **Clone the repository**
   ```bash
   git clone <repository-url>
   cd farmcontrol-api
   ```

2. **Install dependencies**
   ```bash
   npm install
   ```

3. **Environment Configuration**
   Create a `.env` file in the root directory with the following variables:
   ```env
   # Server Configuration
   PORT=8080
   NODE_ENV=development
   
   # Database Configuration
   DB_LINK=mongodb://localhost:27017
   
   # Keycloak Configuration
   KEYCLOAK_AUTH_SERVER_URL=http://localhost:8080/auth
   KEYCLOAK_REALM=your-realm
   KEYCLOAK_CLIENT_ID=your-client-id
   KEYCLOAK_SECRET=your-client-secret
   
   # Application Configuration
   APP_URL_CLIENT=http://localhost:5173
   LOG_LEVEL=info
   
   # Optional: Scheduled Operations
   SCHEDULE_HOUR=24
   ```

4. **Database Setup**
   ```bash
   # Seed the database with initial data
   npm run seed
   
   # Clear database (if needed)
   npm run clear
   ```

5. **Start the server**
   ```bash
   # Development mode with auto-reload
   npm run dev
   
   # Production mode
   npm start
   ```

## 📚 API Endpoints

### Authentication
- `POST /auth/login` - User login
- `POST /auth/logout` - User logout
- `GET /auth/verify` - Verify authentication status

### Production
- `GET /printers` - Get all printers
- `POST /printers` - Create new printer
- `GET /jobs` - Get all jobs
- `POST /jobs` - Create new job
- `GET /gcodefiles` - Get all G-code files
- `POST /gcodefiles` - Upload G-code file
- `GET /filaments` - Get all filaments

### Inventory
- `GET /partstocks` - Get part stock levels
- `POST /partstocks` - Update part stock
- `GET /filamentstocks` - Get filament stock levels
- `POST /filamentstocks` - Update filament stock
- `GET /stockevents` - Get stock events
- `GET /stockaudits` - Get stock audits

### Management
- `GET /users` - Get all users
- `POST /users` - Create new user
- `GET /users/:id` - Get user by ID
- `PUT /users/:id` - Update user
- `DELETE /users/:id` - Delete user
- `GET /parts` - Get all parts
- `POST /parts` - Create new part
- `GET /products` - Get all products
- `POST /products` - Create new product
- `GET /vendors` - Get all vendors
- `POST /vendors` - Create new vendor
- `GET /materials` - Get all materials
- `POST /materials` - Create new material
- `GET /auditlogs` - Get audit logs
- `GET /notetypes` - Get note types
- `POST /notetypes` - Create note type

### Miscellaneous
- `GET /spotlight` - Get system spotlight data
- `GET /notes` - Get all notes
- `POST /notes` - Create new note

## 🏗️ Project Structure

```
farmcontrol-api/
├── src/
│   ├── database/          # Database connection and utilities
│   │   ├── inventory/     # Inventory-related routes
│   │   ├── management/    # Management routes
│   │   ├── misc/          # Miscellaneous routes
│   │   └── production/    # Production-related routes
│   ├── schemas/           # MongoDB schemas
│   ├── services/          # Business logic services
│   ├── keycloak.js        # Keycloak configuration
│   └── index.js           # Main application entry point
├── images/                # Static images
├── package.json           # Project dependencies and scripts
└── README.md             # This file
```

## 🔧 Configuration

### Keycloak Setup
The application uses Keycloak for authentication. Configure your Keycloak server with:
- A realm for your application
- A client with confidential access type
- Appropriate roles (admin, creator, member)
- Valid redirect URIs

### Database Configuration
The application uses MongoDB. Ensure your MongoDB instance is running and accessible at the configured `DB_LINK`.

### CORS Configuration
The application is configured to allow requests only from the specified `APP_URL_CLIENT`. Update this in your environment configuration.

## 🚀 Deployment

### Development
```bash
npm run dev
```

### Production
```bash
npm start
```

### Docker (if applicable)
```bash
docker build -t farmcontrol-api .
docker run -p 8080:8080 farmcontrol-api
```

## 📊 Monitoring and Logging

The application uses log4js for comprehensive logging. Log levels can be configured via the `LOG_LEVEL` environment variable:
- `trace` - Most verbose
- `debug` - Debug information
- `info` - General information
- `warn` - Warning messages
- `error` - Error messages
- `fatal` - Fatal errors only

## 🔄 Scheduled Operations

The application includes scheduled operations for data maintenance:
- Automatic database reseeding (configurable via `SCHEDULE_HOUR`)
- Audit log maintenance
- System health checks

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📝 License

This project is licensed under the ISC License.

## 🆘 Support

For support and questions:
- Check the API documentation
- Review the audit logs for debugging
- Contact the development team

## 🔄 Version History

- **v1.0.0** - Initial release with core functionality
  - Production management
  - Inventory control
  - User management
  - Authentication with Keycloak
  - Comprehensive audit logging