etsy-finance-tracker/README.md

# Etsy Business Tracker

A comprehensive web application for tracking and managing your Etsy business operations, including products, orders, customers, analytics, and expenses.

## 🚀 Features

- **Dashboard**: Real-time overview of business metrics and KPIs
- **Product Management**: Track product listings, variations, pricing, and inventory
- **Order Tracking**: Monitor order status, fulfillment, and shipping
- **Customer Management**: Manage customer data, purchase history, and communication
- **Sales Analytics**: Revenue tracking, profit margins, and trend analysis
- **Expense Tracking**: Business expenses, tax deductions, and cost analysis
- **Inventory Management**: Stock levels, reorder alerts, and supplier tracking
- **Financial Reports**: P&L statements, tax reports, and business insights

## 🛠 Tech Stack

### Frontend
- **React 18** with TypeScript
- **Vite** for fast development and building
- **Tailwind CSS** for styling
- **Redux Toolkit** for state management
- **React Router** for navigation
- **Chart.js** for data visualization
- **React Hook Form** with Zod validation

### Backend
- **Node.js** with Express and TypeScript
- **MongoDB** with Mongoose ODM
- **JWT** authentication
- **bcryptjs** for password hashing
- **Helmet** for security
- **Express Rate Limit** for API protection
- **Morgan** for logging
- **Cors** for cross-origin requests

## 📦 Project Structure

```
etsy-tracker/
├── client/                 # React frontend
│   ├── src/
│   │   ├── components/     # Reusable UI components
│   │   ├── pages/         # Page components
│   │   ├── store/         # Redux store and slices
│   │   ├── utils/         # Utility functions
│   │   └── ...
│   ├── public/
│   └── package.json
├── server/                 # Node.js backend
│   ├── src/
│   │   ├── controllers/   # Route handlers
│   │   ├── models/        # Database models
│   │   ├── routes/        # API routes
│   │   ├── middleware/    # Custom middleware
│   │   └── index.ts       # Server entry point
│   ├── .env.example
│   └── package.json
├── .github/
│   └── copilot-instructions.md
├── package.json           # Root package.json
└── README.md
```

## 🚀 Getting Started

### Quick Deploy (Recommended)

**Option 1: GitHub Container Registry (Fastest)**
```bash
git clone https://github.com/dlawler489/etsy-finance-tracker.git
cd etsy-finance-tracker
mkdir -p data/{csv,pdf,spreadsheets}
./build-deploy.sh ghcr
```

**Option 2: Local Docker Build**
```bash
git clone https://github.com/dlawler489/etsy-finance-tracker.git
cd etsy-finance-tracker
./build-deploy.sh local
```

Both options will start the application at **http://localhost:3000**

### Development Setup

For development and customization:

### Prerequisites

- Node.js (v18 or higher)
- npm or yarn
- Docker Desktop (for containerized deployment)

### Installation

1. **Clone the repository**
   ```bash
   git clone https://github.com/dlawler489/etsy-finance-tracker.git
   cd etsy-finance-tracker
   ```

2. **Install dependencies**
   ```bash
   cd client && npm install && cd ..
   cd server && npm install && cd ..
   ```

3. **Set up environment variables (optional)**
   ```bash
   cd server
   cp .env.example .env
   # Edit .env if needed for development
   ```

### Development

**Option 1: Run both servers with Docker (recommended)**
```bash
./build-deploy.sh local
```

**Option 2: Run development servers separately**
```bash
npm run dev
```

**Option 2: Run servers separately**

Start the backend server:
```bash
npm run server:dev
# Server runs on http://localhost:8080
```

Start the frontend development server:
```bash
npm run client:dev
# Client runs on http://localhost:3000 (or next available port)
```

### Building for Production

```bash
# Build both client and server
npm run build

# Or build separately
npm run client:build
npm run server:build
```

### Running Tests

```bash
npm test
```

## 🔧 Configuration

### Environment Variables (Server)

Create a `.env` file in the `server` directory:

```env
NODE_ENV=development
PORT=8080
CLIENT_URL=http://localhost:3000
MONGODB_URI=mongodb://localhost:27017/etsy-tracker
JWT_SECRET=your-super-secret-jwt-key-change-this-in-production
SESSION_SECRET=your-super-secret-session-key-change-this-in-production
```

### Database Setup

The application uses MongoDB to store:
- **Products**: Product details, variants, pricing, inventory
- **Orders**: Order information, customer details, status tracking
- **Customers**: Customer profiles, purchase history
- **Expenses**: Business expense records
- **Users**: Authentication and user management

## 📊 API Endpoints

### Authentication
- `POST /api/auth/register` - User registration
- `POST /api/auth/login` - User login
- `POST /api/auth/logout` - User logout
- `GET /api/auth/me` - Get current user

### Products
- `GET /api/products` - Get all products
- `POST /api/products` - Create new product
- `GET /api/products/:id` - Get specific product
- `PUT /api/products/:id` - Update product
- `DELETE /api/products/:id` - Delete product

### Orders
- `GET /api/orders` - Get all orders
- `POST /api/orders` - Create new order
- `GET /api/orders/:id` - Get specific order
- `PUT /api/orders/:id` - Update order status

### Customers
- `GET /api/customers` - Get all customers
- `POST /api/customers` - Create new customer
- `GET /api/customers/:id` - Get specific customer
- `PUT /api/customers/:id` - Update customer

### Expenses
- `GET /api/expenses` - Get all expenses
- `POST /api/expenses` - Create new expense
- `PUT /api/expenses/:id` - Update expense
- `DELETE /api/expenses/:id` - Delete expense

### Analytics
- `GET /api/analytics/dashboard` - Get dashboard metrics
- `GET /api/analytics/sales` - Get sales analytics
- `GET /api/analytics/products` - Get product performance
- `GET /api/analytics/customers` - Get customer analytics

## 🎨 UI/UX

The application features a modern, responsive design built with Tailwind CSS:
- **Responsive Design**: Works on desktop, tablet, and mobile devices
- **Dark/Light Mode**: User preference support
- **Interactive Charts**: Visual analytics and reporting
- **Form Validation**: Real-time validation with helpful error messages
- **Toast Notifications**: User feedback for actions

## 🔒 Security Features

- **JWT Authentication**: Secure token-based authentication
- **Password Hashing**: bcrypt for secure password storage
- **Rate Limiting**: API endpoint protection
- **CORS Configuration**: Cross-origin request handling
- **Input Validation**: Server-side validation for all inputs
- **Security Headers**: Helmet.js for security headers

## 🚀 Deployment

### Using PM2 (Recommended for production)

```bash
# Build the application
npm run build

# Install PM2 globally
npm install -g pm2

# Start the server with PM2
cd server
pm2 start dist/index.js --name "etsy-tracker-api"

# Serve the client (using a static file server)
pm2 serve client/dist 3000 --name "etsy-tracker-client"
```

### Using Docker

```bash
# Build and run with Docker Compose
docker-compose up --build
```

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/new-feature`
3. Commit your changes: `git commit -am 'Add new feature'`
4. Push to the branch: `git push origin feature/new-feature`
5. Submit a pull request

## 📝 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🆘 Troubleshooting

### Common Issues

1. **Port already in use**: If you get an EADDRINUSE error, kill the process using the port:
   ```bash
   lsof -ti:8080 | xargs kill -9
   ```

2. **MongoDB connection issues**: Ensure MongoDB is running and the connection string is correct in your `.env` file.

3. **Build errors**: Clear node_modules and reinstall:
   ```bash
   rm -rf node_modules client/node_modules server/node_modules
   npm run install:all
   ```

### VS Code Integration

This project includes VS Code configuration for:
- **Tasks**: Pre-configured build and dev tasks
- **Debugging**: Launch configurations for both client and server
- **Extensions**: Recommended extensions list
- **Settings**: Project-specific settings

## 📞 Support

If you encounter any issues or have questions, please:
1. Check the troubleshooting section above
2. Search existing issues in the repository
3. Create a new issue with detailed information about the problem

---

**Built with ❤️ for Etsy sellers who want to grow their business through better data tracking and analysis.**