studspider-status/README.md

StudSpider Status Dashboard

A real-time inventory management dashboard that integrates with Square POS, Brickset.com, and a SQL database to track and visualize LEGO inventory changes.

📋 Overview

StudSpider Status is a comprehensive dashboard application designed to monitor and track inventory discrepancies between Square's inventory system and actual stock levels. The application provides real-time insights into inventory changes, theme distributions, and system statistics.

🎯 Key Features

• Real-Time Inventory Tracking: Monitor changes between Square inventory and database records
• Square Integration: Direct integration with Square POS API for inventory management
• Brickset.com API: Fetch LEGO set information and theme data
• SQL Database Backend: Persistent storage for tracking historical inventory changes
• Visual Analytics: Interactive charts and graphs showing inventory distribution by theme
• Change Log: Detailed timeline of all inventory modifications (additions, updates, deletions)
• Statistics Dashboard: Quick overview of total sets, themes, and recent changes

🛠️ Technology Stack

Frontend

• Vue 3: Modern reactive JavaScript framework with Composition API
• Vuetify 3: Material Design component library
• Vue Router: Client-side routing for single-page application
• Pinia: State management solution
• Vite: Next-generation frontend build tool
• ApexCharts/Vuetify Charts: Data visualization

Backend Integration

• Square API: Point of sale and inventory management
• Brickset API: LEGO set database and information
• SQL Database: Inventory change tracking and historical data

📦 Installation

Prerequisites

• Node.js (v16 or higher)
• pnpm (recommended) or npm
• Access to Square API credentials
• Brickset API key
• SQL database connection

Setup

1. Clone the repository:

git clone <repository-url>
cd studspider-status

2. Install dependencies:

pnpm install

3. Configure environment variables: Create a .env file in the root directory:

VITE_SQUARE_API_KEY=your_square_api_key
VITE_SQUARE_ACCESS_TOKEN=your_square_access_token
VITE_BRICKSET_API_KEY=your_brickset_api_key
VITE_DATABASE_URL=your_database_connection_string

4. Start the development server:

pnpm dev

5. Build for production:

pnpm build

🚀 Usage

Development

pnpm dev

Access the application at http://localhost:5173

Production Build

pnpm build
pnpm preview

Linting

pnpm lint

📊 Features Breakdown

Dashboard View

• Recent Changes Panel: Real-time list of inventory modifications with timestamps
• Statistics Cards: Quick metrics showing total sets, total themes, and weekly changes
• Theme Distribution Chart: Visual pie chart displaying inventory breakdown by LEGO theme

Navigation

• Dashboard: Main inventory overview
• Review: Inventory review and reconciliation
• Statistics: Detailed analytics and reporting
• Demo: Component showcase and UI examples

🔌 API Integration

Square API

The application connects to Square's Inventory API to:

• Fetch current inventory levels
• Track inventory adjustments
• Monitor stock changes in real-time

Brickset API

Integration with Brickset.com provides:

• LEGO set information and details
• Theme categorization
• Set metadata and specifications

Database

SQL database stores:

• Historical inventory snapshots
• Change logs with timestamps
• User actions and modifications
• Theme and set relationships

📁 Project Structure

studspider-status/
├── src/
│   ├── assets/          # Static assets
│   ├── components/      # Reusable Vue components
│   │   ├── AppFooter.vue
│   │   ├── HelloWorld.vue
│   │   └── DynamicPieChart.vue
│   ├── layouts/         # Page layout templates
│   │   └── default.vue
│   ├── pages/           # Application pages (auto-routed)
│   │   ├── index.vue    # Dashboard home page
│   │   ├── demo.vue     # Component demo page
│   │   ├── stats.vue    # Statistics page
│   │   └── review.vue   # Review page
│   ├── plugins/         # Vue plugins (Vuetify, Router, etc.)
│   │   ├── index.js
│   │   └── vuetify.js
│   ├── router/          # Vue Router configuration
│   │   └── index.js
│   ├── stores/          # Pinia state management
│   │   ├── app.js
│   │   └── index.js
│   ├── styles/          # Global styles and SCSS
│   │   └── settings.scss
│   ├── App.vue          # Root application component
│   └── main.js          # Application entry point
├── public/              # Public static files
├── .env                 # Environment variables (not committed)
├── package.json         # Project dependencies
├── vite.config.mjs      # Vite configuration
└── README.md           # This file

🎨 Customization

Adding New Pages

1. Create a new .vue file in src/pages/
2. Add route metadata at the bottom:

<route lang="yaml">
name: yourpage
layout: default
</route>

3. Add navigation item in App.vue:

<v-list-item
  prepend-icon="mdi-your-icon"
  title="Your Page"
  value="yourpage"
  to="/yourpage"
/>

Modifying Themes

Edit the color palette in component files or update Vuetify theme settings in src/plugins/vuetify.js.

🔒 Security Notes

• Never commit API keys or sensitive credentials
• Use environment variables for all API configuration
• Implement proper authentication for production deployments
• Secure database connections with appropriate credentials

🐛 Troubleshooting

Development Server Won't Start

# Clear node modules and reinstall
rm -rf node_modules
pnpm install

# Clear Vite cache
rm -rf .vite

Routing Not Working

• Ensure all pages have proper route metadata
• Check that unplugin-vue-router is configured in vite.config.mjs
• Verify the layout system is properly set up

📝 License

[Add your license here]

👥 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Open a Pull Request

🔮 Future Enhancements

• Real-time WebSocket updates for inventory changes
• Export reports to PDF/Excel
• Advanced filtering and search capabilities
• User authentication and role-based access
• Email notifications for inventory discrepancies
• Mobile app version
• Automated inventory reconciliation
• Barcode scanning integration
• Multi-location inventory support

📧 Support

For issues and questions, please open an issue on the GitHub repository.

---

Built with ❤️ using Vue 3 and Vuetify 3