kanban-app/README.md

# Crafting Shop - Fullstack E-commerce Application

A production-ready fullstack e-commerce application built with Flask (backend) and React (frontend), featuring user authentication, product management, shopping cart, and order processing.

## 🏗️ Architecture

### Backend
- **Framework**: Flask 3.x (Application Factory Pattern)
- **Language**: Python 3.11
- **ORM**: SQLAlchemy (with Flask-SQLAlchemy)
- **Database**: PostgreSQL
- **Caching**: Redis
- **Authentication**: JWT tokens (Flask-JWT-Extended)
- **API**: RESTful API with Blueprint
- **Migrations**: Flask-Migrate

### Frontend
- **Framework**: React 18
- **Build Tool**: Vite
- **Styling**: Tailwind CSS
- **State Management**: React Context API
- **HTTP Client**: Axios
- **Routing**: React Router

### Infrastructure
- **Containerization**: Docker & Docker Compose
- **Reverse Proxy**: Nginx
- **Monitoring**: Prometheus & Grafana
- **CI/CD**: GitHub Actions

## 📁 Project Structure

```
flask-react-monorepo/
├── backend/
│   ├── app/
│   │   ├── __init__.py          # Flask application factory
│   │   ├── config.py             # Configuration
│   │   ├── models/               # Database models
│   │   │   ├── user.py
│   │   │   ├── product.py
│   │   │   └── order.py
│   │   ├── routes/               # API routes
│   │   │   ├── api.py
│   │   │   └── health.py
│   │   ├── services/             # Business logic
│   │   └── utils/               # Utilities
│   ├── tests/                   # Backend tests
│   ├── requirements/
│   │   ├── base.txt             # Production dependencies
│   │   ├── dev.txt              # Development dependencies
│   │   └── prod.txt             # Production-only dependencies
│   ├── .env.example             # Environment variables template
│   ├── Dockerfile               # Backend Docker image
│   └── wsgi.py                 # WSGI entry point
├── frontend/
│   ├── src/
│   │   ├── components/           # React components
│   │   ├── context/             # React Context API
│   │   ├── hooks/               # Custom React hooks
│   │   ├── pages/               # Page components
│   │   ├── services/            # API services
│   │   ├── App.jsx              # Root component
│   │   └── main.jsx            # Entry point
│   ├── public/                  # Static assets
│   ├── tests/                   # Frontend tests
│   ├── .env.example             # Environment variables template
│   ├── Dockerfile               # Frontend Docker image
│   ├── nginx.conf               # Nginx configuration
│   ├── package.json             # Node dependencies
│   ├── vite.config.js           # Vite configuration
│   ├── tailwind.config.js       # Tailwind CSS configuration
│   └── postcss.config.js       # PostCSS configuration
├── infrastructure/
│   ├── docker-compose/
│   │   ├── docker-compose.dev.yml
│   │   └── docker-compose.prod.yml
│   ├── nginx/
│   │   ├── nginx.conf
│   │   └── sites/
│   ├── monitoring/
│   │   └── prometheus.yml
│   └── scripts/                # Deployment scripts
│       ├── deploy.sh
│       ├── backup.sh
│       └── healthcheck.sh
├── scripts/
│   ├── dev.sh                  # Development setup script
│   └── test.sh                 # Test runner script
├── .github/
│   └── workflows/
│       ├── ci.yml              # Continuous Integration
│       └── cd.yml              # Continuous Deployment
├── docker-compose.yml           # Main Docker Compose configuration
├── .env.example               # Root environment variables template
├── .gitignore                # Git ignore rules
├── Makefile                  # Common commands
└── README.md                 # This file
```

## 🚀 Getting Started

### Prerequisites

- Docker and Docker Compose
- Python 3.11+
- Node.js 18+
- Git

### Installation

1. **Clone repository**
   ```bash
   git clone <repository-url>
   cd crafting_shop_app
   ```

2. **Copy environment files**
   ```bash
   cp .env.example .env
   cp backend/.env.example backend/.env
   ```

3. **Update environment variables** (optional for dev, required for production)
   Edit `.env` and `backend/.env` with your configuration

4. **Install dependencies**
   ```bash
   make install
   ```

### Development Mode (Recommended - Local Servers)

This is the best approach for development - runs backend and frontend locally with Docker for database/redis only.

```bash
# 1. Start development services (postgres & redis only)
make dev-services

# 2. Initialize database (first time only)
cd backend
source venv/bin/activate
flask db init
flask db migrate -m "Initial migration"
flask db upgrade

# 3. Start backend server (in terminal 1)
make dev-backend

# 4. Start frontend server (in terminal 2)
make dev-frontend
```

**Access URLs:**
- Frontend: http://localhost:5173
- Backend API: http://localhost:5000
- PostgreSQL: localhost:5432
- Redis: localhost:6379

**Stop services:**
```bash
make dev-stop-services
```

### Production Mode (Docker)

For production deployment using Docker Compose:

```bash
# 1. Build and start all services
make build
make up

# 2. Access application
# Frontend: http://localhost
# Backend API: http://localhost:5000
# Grafana: http://localhost:3001
# Prometheus: http://localhost:9090
```

## 🛠️ Development

### Setup Development Environment

```bash
# Run the setup script
./scripts/dev.sh

# Or manually:
cd backend
python -m venv venv
source venv/bin/activate
pip install -r requirements/dev.txt

cd ../frontend
npm install
```

### Running Development Servers

```bash
# Using Docker Compose
docker-compose up

# Or run services individually:
cd backend
source venv/bin/activate
flask run

# In another terminal:
cd frontend
npm run dev
```

### Database Management

```bash
# Create migrations
cd backend
source venv/bin/activate
flask db migrate -m "migration message"

# Apply migrations
flask db upgrade

# Open Flask shell
flask shell
```

### Testing

```bash
# Run all tests
make test

# Run backend tests only
make test-backend

# Run frontend tests only
make test-frontend

# Or use the test script
./scripts/test.sh
```

### Code Quality

```bash
# Lint code
make lint

# Format code
make format
```

## 📦 Available Commands

### Development (Local)
```bash
make install            # Install all dependencies
make dev-services      # Start postgres & redis in Docker
make dev-stop-services # Stop postgres & redis
make dev-backend       # Start Flask server locally
make dev-frontend      # Start Vite dev server locally
make dev               # Start dev environment (services + instructions)
```

### Production (Docker)
```bash
make build             # Build Docker images
make up                # Start all services in Docker
make down              # Stop all services
make restart           # Restart services
make logs              # View logs
```

### Testing & Quality
```bash
make test              # Run all tests
make test-backend      # Run backend tests only
make test-frontend     # Run frontend tests only
make lint              # Run all linters
make lint-backend      # Lint backend only
make lint-frontend     # Lint frontend only
make format            # Format all code
```

### Database & Utilities
```bash
make migrate           # Run database migrations
make shell             # Open Flask shell
make clean             # Clean build artifacts
make prune             # Remove unused Docker resources
make backup            # Backup database
```

## 🔧 Configuration

### Backend Configuration

The backend uses environment variables defined in `backend/.env`:

- `FLASK_ENV`: Environment (development/production)
- `SECRET_KEY`: Flask secret key
- `JWT_SECRET_KEY`: JWT signing key
- `DATABASE_URL`: PostgreSQL connection string

### Frontend Configuration

The frontend is configured through:
- `vite.config.js`: Vite build configuration
- `tailwind.config.js`: Tailwind CSS configuration
- `.env`: Environment variables (if needed)

### Infrastructure Configuration

- `docker-compose.yml`: Service orchestration
- `infrastructure/monitoring/prometheus.yml`: Metrics scraping

## 🧪 Testing

### Backend Tests

```bash
cd backend
pytest --cov=app --cov-report=html
```

### Frontend Tests

```bash
cd frontend
npm test -- --run --coverage
```

## 🚢 Deployment

### Using Docker Compose

```bash
# Production deployment
docker-compose -f docker-compose.prod.yml up -d
```

### Using CI/CD

The GitHub Actions workflow handles:
1. **CI**: Runs tests on every push/PR
2. **CD**: Deploys to production on main branch push

### Manual Deployment

1. Build and push Docker images
2. Update ECS task definitions
3. Deploy to ECS cluster

## 📊 Monitoring

- **Prometheus**: http://localhost:9090
  - Metrics from backend, database, and Redis
- **Grafana**: http://localhost:3001
  - Default credentials: admin / admin (change in .env)
  - Dashboards for application monitoring

## 🔒 Security

- JWT-based authentication
- Environment variable management
- CORS configuration
- SQL injection prevention (SQLAlchemy ORM)
- XSS prevention (React escaping)

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add 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 MIT License.

## 🙏 Acknowledgments

- Flask and React communities
- Docker and Docker Compose
- Vite for fast development
- Tailwind CSS for styling