peikarband/docs/PROJECT_STRUCTURE.md

# ساختار پروژه پیکربند - Landing Page

## 📁 ساختار کلی (بازسازی شده)

```
peikarband-landing/
├── README.md              # Main project documentation
├── requirements.txt       # Production dependencies
├── requirements-dev.txt   # Development dependencies
├── Makefile              # Build automation commands
├── rxconfig.py           # Reflex config loader (imports from config/)
├── .gitignore
│
├── build/                # 🔨 همه چیز مربوط به Build
│   ├── docker/
│   │   ├── Dockerfile             # Main application Dockerfile
│   │   ├── Dockerfile.base        # Base image (reference)
│   │   ├── docker-compose.yml     # Local development setup
│   │   └── .dockerignore
│   └── ci/
│       └── woodpecker.yml         # CI/CD pipeline configuration
│
├── deploy/               # 🚀 همه چیز مربوط به Deployment
│   ├── helm/
│   │   └── peikarband/           # Helm chart
│   │       ├── Chart.yaml
│   │       ├── templates/        # K8s resource templates
│   │       ├── values.yaml       # Default values
│   │       ├── values-production.yaml
│   │       └── values-staging.yaml
│   ├── kubernetes/
│   │   └── secrets-template.yaml # K8s manifest templates
│   └── argocd/                   # ArgoCD GitOps configs
│       ├── application.yaml
│       ├── application-staging.yaml
│       ├── README.md
│       └── secrets/
│
├── config/               # ⚙️ همه Configuration Files
│   ├── alembic.ini                # Database migration config
│   ├── mypy.ini                   # Type checking config
│   ├── pytest.ini                 # Test configuration
│   └── reflex.config.py           # Reflex app configuration
│
├── tools/                # 🔧 Scripts و ابزارهای کمکی
│   ├── scripts/
│   │   ├── update-env-json.sh    # Runtime config updater
│   │   └── diagnose-502.sh       # Diagnostic tools
│   └── setup.py                   # Package setup
│
├── assets/               # 🎨 Static Assets (served by Reflex)
│   ├── logo.png
│   ├── banner-3.gif
│   ├── custom.css
│   ├── hero-*.svg
│   └── wordpress*.gif
│
├── data/                 # 💾 Local Data (gitignored)
│   ├── db/              # Local database files
│   ├── cache/           # Cache files
│   └── logs/            # Log files
│
├── src/                  # 💻 Source Code (Clean Architecture)
│   ├── config/          # Application configuration
│   │   ├── settings.py
│   │   ├── database.py
│   │   ├── cache.py
│   │   └── logging.py
│   ├── core/            # Core business logic
│   │   ├── domain/      # Domain layer
│   │   │   ├── entities/      # Domain entities
│   │   │   ├── value_objects/ # Value objects
│   │   │   ├── enums/         # Domain enums
│   │   │   └── exceptions/    # Domain exceptions
│   │   └── application/ # Application layer
│   │       ├── use_cases/     # Use cases
│   │       ├── dto/           # Data Transfer Objects
│   │       ├── interfaces/    # Interfaces/Ports
│   │       └── validators/    # Validators
│   ├── infrastructure/  # Infrastructure layer
│   │   ├── database/    # Database implementation
│   │   │   ├── models/        # SQLAlchemy models
│   │   │   ├── repositories/  # Repository implementations
│   │   │   └── migrations/    # Alembic migrations
│   │   ├── cache/       # Cache implementation (Redis)
│   │   ├── external/    # External API integrations
│   │   │   ├── email/
│   │   │   ├── sms/
│   │   │   ├── payment/
│   │   │   └── providers/
│   │   ├── security/    # Security implementations
│   │   └── tasks/       # Background tasks (Celery)
│   ├── presentation/    # Presentation layer
│   │   ├── web/         # Reflex web application
│   │   │   ├── pages/         # Reflex pages
│   │   │   ├── components/    # Reusable components
│   │   │   ├── state/         # Application state
│   │   │   └── styles/        # Styling
│   │   └── api/         # REST API endpoints (if needed)
│   │       ├── routes/
│   │       └── middleware/
│   └── shared/          # Shared utilities
│       ├── events/      # Event system
│       └── messaging/   # Message bus
│
├── tests/                # 🧪 Test Suites
│   ├── unit/            # Unit tests
│   │   ├── core/
│   │   └── infrastructure/
│   ├── integration/     # Integration tests
│   │   ├── database/
│   │   └── external/
│   ├── e2e/             # End-to-end tests
│   │   └── scenarios/
│   ├── fixtures/        # Test fixtures
│   └── conftest.py      # Pytest configuration
│
├── docs/                 # 📚 Documentation
│   ├── api/             # API documentation
│   ├── architecture/    # Architecture docs
│   │   ├── overview.md
│   │   └── database-strategy.md
│   ├── deployment/      # Deployment guides
│   │   ├── DEPLOYMENT_CHECKLIST.md
│   │   ├── DEPLOYMENT_QUICK_START.md
│   │   ├── PRODUCTION_DEPLOYMENT.md
│   │   ├── CHANGELOG-DEPLOYMENT.md
│   │   └── kubernetes.md
│   ├── development/     # Development guides
│   │   ├── setup.md
│   │   ├── coding-standards.md
│   │   └── git-workflow.md
│   ├── changelog/       # Change logs
│   │   ├── CHANGELOG.md
│   │   ├── migrations.md
│   │   └── known-issues.md
│   ├── operations/      # Operations docs
│   ├── handbook.md      # Complete handbook
│   └── PROJECT_STRUCTURE.md # This file
│
└── tmp/                  # Temporary files (gitignored)
```

## 🎯 معماری جدید - Separation of Concerns

### 1. `build/` - Build Configurations
**هدف**: جداسازی همه چیز مربوط به build process

- **`build/docker/`**: تمام فایل‌های Docker
  - Multi-stage Dockerfile با optimization
  - Docker Compose برای development
  - .dockerignore

- **`build/ci/`**: CI/CD configurations
  - Woodpecker CI pipeline
  - سایر CI configs (GitHub Actions, GitLab CI)

**مزایا**:
- ✅ Root directory تمیزتر
- ✅ Build configs مدیریت شده در یک مکان
- ✅ CI/CD configs جدا از کد

### 2. `deploy/` - Deployment Configurations
**هدف**: تمرکز همه deployment configs

- **`deploy/helm/`**: Helm charts
  - Production و Staging values
  - Templates برای تمام K8s resources

- **`deploy/kubernetes/`**: Raw K8s manifests
  - Secret templates
  - Custom resources

- **`deploy/argocd/`**: ArgoCD GitOps
  - Application definitions
  - Sync policies

**مزایا**:
- ✅ یک مکان برای همه deployment
- ✅ واضح برای DevOps engineers
- ✅ جداسازی از source code

### 3. `config/` - Configuration Files
**هدف**: تمرکز همه config files

- `alembic.ini`: Database migrations
- `mypy.ini`: Type checking
- `pytest.ini`: Testing
- `reflex.config.py`: Reflex framework

**مزایا**:
- ✅ Root directory خلوت‌تر
- ✅ Configs به راحتی پیدا می‌شوند
- ✅ مدیریت بهتر

### 4. `tools/` - Utility Scripts
**هدف**: جداسازی scripts و ابزارها

- Runtime scripts
- Diagnostic tools
- Setup utilities

**مزایا**:
- ✅ Scripts منظم و دسته‌بندی شده
- ✅ جدا از source code

### 5. `assets/` - Consolidated Assets
**هدف**: یک مکان واحد برای همه static assets

**قبلاً**: Assets پراکنده در `assets/` و `src/presentation/web/assets/`
**الان**: همه در `assets/` (served directly by Reflex)

**فایل‌های موجود**:
- `logo.png` - لوگوی پیکربند
- `banner-3.gif` - Banner animation
- `wordpress-logo.gif` - WordPress logo
- `hero-*.svg` - Hero section icons
- `custom.css` - Custom styles

**استفاده در کد**:
```python
rx.image(src="/logo.png")  # Reflex serves from /assets
```

**مزایا**:
- ✅ No duplication
- ✅ یک منبع حقیقت
- ✅ مدیریت آسان‌تر
- ✅ سازگار با Reflex

### 6. `data/` - Local Data (gitignored)
**هدف**: Local development data

- `data/db/`: SQLite و database files
- `data/cache/`: Redis dumps
- `data/logs/`: Log files

**مزایا**:
- ✅ Data جدا از code
- ✅ .gitignore شده
- ✅ Clean repository

## 🔗 ارتباط با پروژه‌های دیگر

### Base Image Repository
- **Repo**: `peikarband/base`
- **Registry**: `hub.peikarband.ir/peikarband/base:latest`
- **Purpose**: Base image with Python, Node.js, bun, build tools
- **Build**: Separate CI/CD pipeline
- **Usage**: Referenced in `build/docker/Dockerfile`

### Landing Page (This Repo)
- **Repo**: `peikarband/landing`
- **Registry**: `hub.peikarband.ir/peikarband/landing:latest`
- **Purpose**: Landing page application
- **Dependencies**: Uses base image

## 📝 فایل‌های Root (Minimal)

### ضروری
- `README.md`: Main documentation
- `requirements.txt`: Dependencies
- `Makefile`: Build commands
- `rxconfig.py`: Reflex config loader
- `.gitignore`: Git ignore rules

### حذف شده از Root
- ❌ `Dockerfile` → `build/docker/`
- ❌ `docker-compose.yml` → `build/docker/`
- ❌ `.woodpecker.yml` → `build/ci/`
- ❌ `alembic.ini` → `config/`
- ❌ `pytest.ini` → `config/`
- ❌ `mypy.ini` → `config/`
- ❌ `scripts/` → `tools/scripts/`
- ❌ `setup.py` → `tools/`
- ❌ `helm/` → `deploy/helm/`
- ❌ `argocd/` → `deploy/argocd/`
- ❌ Duplicate assets → `assets/static/`

## 🎯 Best Practices

### Root Directory
- ✅ فقط فایل‌های ضروری
- ✅ Config files در `config/`
- ✅ Build files در `build/`
- ✅ Deploy files در `deploy/`

### Source Code (`src/`)
- ✅ Clean Architecture layers
- ✅ Separation of concerns
- ✅ SOLID principles

### Documentation
- ✅ همه docs در `docs/`
- ✅ دسته‌بندی منطقی
- ✅ به‌روز و جامع

### Deployment
- ✅ Helm charts محیط‌محور
- ✅ ArgoCD GitOps
- ✅ Secrets جدا از code

### Testing
- ✅ Unit/Integration/E2E جدا
- ✅ Fixtures منظم
- ✅ Coverage بالا

## 🚀 مزایای معماری جدید

1. **Clarity** ✨
   - واضح است که هر فایل کجا باشد
   - Navigation آسان‌تر

2. **Maintainability** 🔧
   - نگهداری آسان‌تر
   - Onboarding سریع‌تر

3. **Scalability** 📈
   - اضافه کردن configs جدید ساده
   - مقیاس‌پذیری بهتر

4. **Professional** 💼
   - استاندارد enterprise projects
   - Best practices معماری

5. **Developer Experience** 👨‍💻
   - کم‌تر سردرگم
   - Productivity بالاتر

## 📊 مقایسه قبل و بعد

### قبل
```
root/
├── 15+ config files  😰
├── Docker files
├── CI configs
├── helm/
├── argocd/
├── scripts/
├── assets/ (duplicate!)
└── src/
```

### بعد
```
root/
├── 4 essential files only  😌
├── build/         (organized)
├── deploy/        (organized)
├── config/        (organized)
├── tools/         (organized)
├── assets/static/ (consolidated)
└── src/           (clean)
```

---

**آخرین بروزرسانی**: 2025-01-30
**نسخه معماری**: 2.0 (Restructured)