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

   git clone <repository-url>
   cd crafting_shop_app
   

2. Copy environment files

   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

   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.

# 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:

make dev-stop-services

Production Mode (Docker)

For production deployment using Docker Compose:

# 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

# 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

# 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

# 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

# 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

# Lint code
make lint

# Format code
make format

📦 Available Commands

Development (Local)

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)

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

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

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

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

Frontend Tests

cd frontend
npm test -- --run --coverage

🚢 Deployment

Using Docker Compose

# 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