From 02d83335ee2ea8338fa2873ba429f9839d89e486 Mon Sep 17 00:00:00 2001 From: cproudlock Date: Tue, 13 Jan 2026 17:13:05 -0500 Subject: [PATCH] Add README with project documentation and naming conventions Documents database and code naming standards (single word, no underscores), project structure, setup instructions, and API reference. Co-Authored-By: Claude Opus 4.5 --- README.md | 198 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 198 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..5a8e8dc --- /dev/null +++ b/README.md @@ -0,0 +1,198 @@ +# ShopDB Flask + +A modern rewrite of the classic ASP/VBScript ShopDB application using Flask (Python) and Vue 3. This application manages shop floor machines, PCs, printers, applications, and related infrastructure for manufacturing environments. + +## Overview + +ShopDB tracks and manages: +- **Machines** - CNC equipment, CMMs, inspection systems, etc. +- **PCs** - Shopfloor computers, engineering workstations +- **Printers** - Network printers with Zabbix integration +- **Applications** - Software deployed across the shop floor +- **Knowledge Base** - Documentation and troubleshooting guides + +## Tech Stack + +**Backend:** +- Python 3.x with Flask +- SQLAlchemy ORM +- MySQL 5.6+ database +- JWT authentication +- Plugin architecture for extensibility + +**Frontend:** +- Vue 3 with Composition API +- Vue Router for navigation +- Pinia for state management +- Vite build system + +## Project Structure + +``` +shopdb-flask/ +├── shopdb/ # Flask application +│ ├── core/ +│ │ ├── api/ # REST API endpoints +│ │ ├── models/ # SQLAlchemy models +│ │ ├── schemas/ # Validation schemas +│ │ └── services/ # Business logic +│ ├── plugins/ # Plugin system +│ └── utils/ # Shared utilities +├── frontend/ # Vue 3 application +│ ├── src/ +│ │ ├── api/ # API client +│ │ ├── components/ # Reusable components +│ │ ├── views/ # Page components +│ │ ├── router/ # Route definitions +│ │ └── stores/ # Pinia stores +│ └── public/ # Static assets +├── plugins/ # External plugins +├── database/ # Database schema exports +├── scripts/ # Import and utility scripts +└── tests/ # Test suite +``` + +## Naming Conventions + +To maintain consistency with the legacy ShopDB database and codebase, the following naming standards apply: + +### Database + +- **Table names:** Lowercase, single word, no underscores or dashes + - Examples: `machines`, `pctypes`, `machinetypes`, `businessunits` +- **Column names:** Lowercase, single word, no underscores or dashes + - Examples: `machineid`, `machinenumber`, `pctypeid`, `isactive`, `createddate` +- **Foreign keys:** Referenced table name + `id` + - Examples: `locationid`, `vendorid`, `modelnumberid`, `pctypeid` +- **Boolean columns:** Prefixed with `is` or `has` + - Examples: `isactive`, `isshopfloor`, `isvnc`, `iswinrm`, `islicenced` + +### Code + +- **Python variables:** Follow database naming where applicable (lowercase, no underscores for model fields) +- **JavaScript variables:** camelCase for local variables, but match API field names from backend +- **Vue components:** PascalCase for component names +- **CSS classes:** Lowercase with dashes for multi-word classes + +### API + +- **Endpoints:** Lowercase, plural nouns + - Examples: `/api/machines`, `/api/pctypes`, `/api/locations` +- **Query parameters:** Lowercase, single word + - Examples: `?type=pc`, `?locationid=5`, `?isactive=true` + +## Style Guidelines + +- No emojis in code, comments, documentation, or UI +- Keep UI functional and professional +- Dark theme is the default +- Consistent table layouts across all list views + +## Setup + +### Prerequisites + +- Python 3.8+ +- Node.js 18+ +- MySQL 5.6+ + +### Backend Setup + +```bash +# Create virtual environment +python -m venv venv +source venv/bin/activate + +# Install dependencies +pip install -r requirements.txt + +# Configure environment +cp .env.example .env +# Edit .env with your database credentials + +# Run development server +flask run +``` + +### Frontend Setup + +```bash +cd frontend + +# Install dependencies +npm install + +# Run development server +npm run dev + +# Build for production +npm run build +``` + +### Database + +The database schema is exported in `database/schema.sql`. To initialize: + +```bash +mysql -u root -p shopdb_flask < database/schema.sql +``` + +To import data from the legacy ShopDB MySQL database: + +```bash +python scripts/import_from_mysql.py +``` + +## Configuration + +Environment variables (`.env`): + +| Variable | Description | +|----------|-------------| +| `DATABASE_URL` | MySQL connection string | +| `SECRET_KEY` | Flask secret key | +| `JWT_SECRET_KEY` | JWT signing key | +| `JWT_ACCESS_TOKEN_EXPIRES` | Access token TTL (seconds) | +| `LOG_LEVEL` | Logging verbosity | + +## API Documentation + +The REST API follows standard conventions: + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/api/machines` | List machines (filterable by type) | +| GET | `/api/machines/:id` | Get machine details | +| POST | `/api/machines` | Create machine | +| PUT | `/api/machines/:id` | Update machine | +| DELETE | `/api/machines/:id` | Soft delete machine | + +Query parameters for list endpoints: +- `page` - Page number (default: 1) +- `per_page` - Items per page (default: 25) +- `sort` - Sort field +- `order` - Sort direction (asc/desc) +- `search` - Search term +- `type` - Filter by machine type (pc, printer, equipment) + +## Plugin System + +ShopDB supports plugins for extending functionality. See `CONTRIBUTING.md` for plugin development guidelines. + +Current plugins: +- **printers** - Extended printer management with Zabbix integration + +## Legacy Migration + +This project replicates functionality from the classic ASP/VBScript ShopDB site. Key mappings: + +| Legacy | Modern | +|--------|--------| +| ASP/VBScript | Flask/Python | +| Classic ADO | SQLAlchemy | +| Server-side HTML | Vue 3 SPA | +| Session auth | JWT tokens | + +## License + +Internal use only.