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

استفاده در کد:

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)