PromptTech/WORKSPACE_STRUCTURE.md

# PromptTech Solutions - Workspace Structure

## 📁 Project Organization

```
PromptTech_Solution_Site/
│
├── 📄 README.md                    # Main project documentation
├── 📄 WORKSPACE_STRUCTURE.md       # This file - workspace organization guide
├── 📄 .gitignore                   # Git ignore rules
├── 📄 yarn.lock                    # Yarn dependencies lock file
├── 📄 nohup.out                    # Background process output
│
├── 📂 backend/                     # Backend FastAPI application
│   ├── server.py                   # Main FastAPI server
│   ├── models.py                   # SQLAlchemy ORM models
│   ├── database.py                 # Database configuration
│   ├── create_admin.py             # Admin user creation script
│   ├── requirements.txt            # Python dependencies
│   └── __pycache__/               # Python cache files
│
├── 📂 frontend/                    # Frontend React application
│   ├── package.json               # Node.js dependencies
│   ├── craco.config.js            # CRACO configuration
│   ├── jsconfig.json              # JavaScript configuration
│   ├── tailwind.config.js         # Tailwind CSS configuration
│   ├── postcss.config.js          # PostCSS configuration
│   ├── components.json            # UI components configuration
│   ├── build/                     # Production build output
│   ├── public/                    # Static assets
│   │   ├── index.html            # HTML template
│   │   └── logo.png              # PTB logo
│   └── src/                       # Source code
│       ├── App.js                # Main app component
│       ├── index.js              # Entry point
│       ├── components/           # React components
│       │   ├── cards/           # Card components
│       │   ├── layout/          # Layout components (Navbar, Footer)
│       │   └── ui/              # shadcn/ui components
│       ├── context/             # React contexts
│       │   ├── AuthContext.js  # Authentication context
│       │   ├── CartContext.js  # Shopping cart context
│       │   └── ThemeContext.js # Theme context
│       ├── hooks/               # Custom React hooks
│       ├── lib/                 # Utility libraries
│       └── pages/               # Page components
│           ├── Home.js
│           ├── Products.js
│           ├── Services.js
│           ├── AdminDashboard.js  # Admin panel
│           └── ...
│
├── 📂 docs/                        # Documentation
│   ├── design_guidelines.json     # Design system guidelines
│   ├── features/                  # Feature documentation
│   │   ├── USER_MANAGEMENT_FEATURE.md
│   │   ├── FEATURE_MULTI_IMAGE_RICHTEXT.md
│   │   └── INVENTORY_FEATURES.md
│   ├── guides/                    # User and admin guides
│   │   ├── ADMIN_GUIDE.md
│   │   ├── PM2_GUIDE.md
│   │   ├── QUICK_START.md
│   │   ├── USAGE_GUIDE.md
│   │   └── README_QUICK_START.txt
│   └── reports/                   # Technical reports
│       ├── DATABASE_HEALTH_REPORT.md
│       ├── DATABASE_OPTIMIZATION_REPORT.md
│       ├── DATABASE_QUICK_REFERENCE.md
│       ├── DEEP_DEBUG_REPORT.md
│       ├── PERFORMANCE_FIXES.md
│       ├── PERFORMANCE_OPTIMIZATIONS.md
│       ├── SERVICES_INVENTORY_REPORT.md
│       ├── SERVICES_STATUS_REPORT.md
│       ├── RELOAD_ISSUE_DIAGNOSIS.md
│       ├── ADMIN_SERVICES_FIX.md
│       ├── FIX_SUMMARY.md
│       ├── PERMANENT_FIX_SUMMARY.md
│       ├── README_REFACTORING.md
│       ├── REFACTORING_COMPLETE.md
│       ├── REFACTORING_REPORT.md
│       ├── ROOT_CAUSE_BROWSER_CACHE.txt
│       ├── IMAGE_UPLOAD_TESTING.md
│       ├── test_inventory_toggle.md
│       └── test_result.md
│
├── 📂 scripts/                     # Utility scripts
│   ├── ecosystem.config.json      # PM2 ecosystem configuration
│   ├── start_backend.sh          # Backend startup script
│   ├── start_frontend.sh         # Frontend startup script
│   ├── start_with_pm2.sh         # PM2 startup script
│   ├── stop_pm2.sh               # PM2 stop script
│   ├── check_services.sh         # Service health check
│   ├── check_status.sh           # Status check script
│   ├── diagnose_services.sh      # Service diagnostics
│   ├── verify_admin_features.sh  # Admin features verification
│   ├── verify_services_complete.sh
│   ├── test_database_integration.sh
│   ├── test_refactoring.sh
│   ├── test_reload_performance.sh
│   ├── test_service_database.sh
│   ├── test_services_complete.sh
│   ├── test_services_inventory.sh
│   ├── deep_debug_test.sh
│   ├── final_verification.sh
│   └── ...
│
├── 📂 tests/                       # Test files
│   ├── __init__.py               # Python test package
│   ├── admin_test.py             # Admin functionality tests
│   ├── backend_test.py           # Backend API tests
│   └── test_api.html             # API testing HTML page
│
├── 📂 test_reports/                # Test execution reports
│   ├── iteration_1.json
│   └── iteration_2.json
│
├── 📂 logs/                        # Application logs
│
├── 📂 Logo/                        # Brand assets
│   └── PTB-logo.png              # PromptTech Solutions logo
│
└── 📂 archive/                     # Archived/deprecated files
    ├── techzone-source/          # Original TechZone source code
    ├── techzone-source.zip       # Original source backup
    └── memory/                   # Old memory/context files
        └── PRD.md
```

## 🗂️ Folder Descriptions

### Core Application Folders

#### `/backend/`

Contains the FastAPI backend application with:

- RESTful API endpoints
- Database models and migrations
- Authentication and authorization
- Admin dashboard APIs
- Image upload handling
- Report generation (CSV, PDF)

**Tech Stack:** Python 3.x, FastAPI 2.0, SQLAlchemy, PostgreSQL, Bcrypt, JWT

#### `/frontend/`

Contains the React frontend application with:

- E-commerce product catalog
- Service booking system
- Shopping cart and checkout
- Admin dashboard with full CRUD
- User authentication
- Image upload and management
- Rich text editor integration

**Tech Stack:** React 19, TipTap 3.15, Tailwind CSS, shadcn/ui, Axios

### Documentation Folders

#### `/docs/features/`

Feature-specific documentation for:

- User Management System (RBAC with 5 roles)
- Multi-image upload with rich text editor
- Inventory management with filters and pagination

#### `/docs/guides/`

User and administrator guides:

- Admin Dashboard Guide
- PM2 Process Manager Guide
- Quick Start Guide
- General Usage Guide

#### `/docs/reports/`

Technical reports and analysis:

- Database optimization reports
- Performance analysis and fixes
- Debugging reports
- Refactoring documentation
- Test results

### Utility Folders

#### `/scripts/`

Operational scripts for:

- Starting/stopping services (PM2)
- Health checks and diagnostics
- Testing and verification
- Database operations

#### `/tests/`

Testing files including:

- Python unit tests
- API integration tests
- HTML test pages

#### `/test_reports/`

JSON reports from test execution iterations

#### `/archive/`

Deprecated or historical files:

- Original TechZone source code
- Old memory/context files
- Backup archives

## 🚀 Quick Access

### Start the Application

```bash
# Using PM2 (recommended)
./scripts/start_with_pm2.sh

# Or start services individually
./scripts/start_backend.sh
./scripts/start_frontend.sh
```

### Access Points

- **Frontend:** <http://localhost:5300>
- **Backend API:** <http://localhost:8181>
- **API Docs:** <http://localhost:8181/docs>

### Admin Access

- **Email:** <admin@techzone.com>
- **Password:** admin123
- **Dashboard:** <http://localhost:5300/admin-dashboard>

## 📚 Key Documentation Files

| File | Description |
|------|-------------|
| [README.md](README.md) | Main project overview |
| [docs/guides/QUICK_START.md](docs/guides/QUICK_START.md) | Get started quickly |
| [docs/guides/ADMIN_GUIDE.md](docs/guides/ADMIN_GUIDE.md) | Admin dashboard usage |
| [docs/guides/PM2_GUIDE.md](docs/guides/PM2_GUIDE.md) | Process management |
| [docs/features/USER_MANAGEMENT_FEATURE.md](docs/features/USER_MANAGEMENT_FEATURE.md) | User management system |
| [docs/features/INVENTORY_FEATURES.md](docs/features/INVENTORY_FEATURES.md) | Inventory management |

## 🛠️ Maintenance Scripts

| Script | Purpose |
|--------|---------|
| `scripts/check_services.sh` | Check service health |
| `scripts/check_status.sh` | View PM2 status |
| `scripts/stop_pm2.sh` | Stop all services |
| `scripts/verify_admin_features.sh` | Test admin features |

## 📝 Notes

- All scripts in `/scripts/` should be executable (`chmod +x script_name.sh`)
- PM2 ecosystem configuration is in `/scripts/ecosystem.config.json`
- Frontend build output is in `/frontend/build/`
- Backend Python virtual environment: `/backend/venv/`
- Database: PostgreSQL (techzone database)
- Uploaded files stored in: `/backend/uploads/`

## 🔐 Environment Variables

Backend uses:

- `DATABASE_URL` - PostgreSQL connection string
- `SECRET_KEY` - JWT token secret
- `CORS_ORIGINS` - Allowed CORS origins

Frontend uses:

- `REACT_APP_BACKEND_URL` - Backend API URL

## 📦 Dependencies

### Backend

See `/backend/requirements.txt` for Python packages

### Frontend

See `/frontend/package.json` for Node.js packages

## 🗄️ Database

- **Database:** techzone
- **User:** techzone_user
- **Port:** 5432
- **Tables:** 15+ tables including users, products, services, orders, etc.

## 📮 Support

For issues or questions, refer to:

1. Quick Start Guide: `docs/guides/QUICK_START.md`
2. Admin Guide: `docs/guides/ADMIN_GUIDE.md`
3. Technical Reports: `docs/reports/`

---

**Last Updated:** January 12, 2026  
**Company:** PromptTech Solutions  
**Project:** E-commerce Platform with Admin Dashboard