Added ReadMe.md
This commit is contained in:
parent
dd4e48f125
commit
ed3fd1c367
221
README.md
Normal file
221
README.md
Normal file
@ -0,0 +1,221 @@
|
||||
# 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:3000
|
||||
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
|
||||
|
||||
### User 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
|
||||
|
||||
### Production Management
|
||||
- `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 Management
|
||||
- `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 /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
|
||||
Loading…
x
Reference in New Issue
Block a user