بنية المجلدات
فهم تخطيط المشروع المُنشأ أمر أساسي للتنقل في تطبيق FORGE وتوسيعه. كل مجلد وملف يخدم غرضاً محدداً، والبنية متسقة عبر جميع المشاريع المُنشأة.
نظرة عامة على المستوى الأعلى
عند تشغيل forge new --name=myapp، يُنشئ FORGE البنية التالية:
myapp/
├── apps/
│ ├── api/ # Rust (Axum) backend
│ ├── web/ # Next.js public website
│ └── admin/ # Next.js admin dashboard
├── database/
│ ├── migrations/ # Versioned SQL migrations
│ └── seeders/ # Default data seeders
├── infra/
│ ├── docker/ # Docker Compose and Dockerfiles
│ ├── caddy/ # Caddyfile for reverse proxy
│ └── certs/ # Local SSL certificates
├── forge.yaml # Project configuration
├── .env # Environment variables (not committed)
├── .env.example # Environment template (committed)
└── .gitignore # Git ignore rulesكل مجلد على المستوى الأعلى يتعلق بمسؤولية مختلفة:
| المجلد | الغرض |
|---|---|
apps/ | كود التطبيقات — مجلد فرعي لكل خدمة |
database/ | ترحيلات قاعدة البيانات وبيانات البذر |
infra/ | إعدادات البنية التحتية (Docker، Caddy، SSL) |
forge.yaml | ملف بيان مشروع FORGE (الإعدادات) |
تطبيق الواجهة البرمجية (apps/api/)
الخلفية بلغة Rust هي تطبيق Axum كامل البنية مع فصل واضح للمسؤوليات:
apps/api/
├── Cargo.toml # Rust dependencies
├── Cargo.lock # Locked dependency versions
├── .env # API environment variables
├── src/
│ ├── main.rs # Application entry point
│ ├── config/
│ │ ├── mod.rs # Config module
│ │ ├── app.rs # App config (name, port, env)
│ │ ├── database.rs # Database connection config
│ │ └── auth.rs # JWT and auth config
│ ├── models/
│ │ ├── mod.rs # Model re-exports
│ │ ├── user.rs # User model (struct + queries)
│ │ ├── role.rs # Role model with permissions
│ │ ├── permission.rs # Permission model
│ │ ├── content.rs # CMS content pages
│ │ ├── menu.rs # Navigation menus
│ │ ├── media.rs # Media/file uploads
│ │ ├── lookup.rs # Lookup/reference tables
│ │ └── audit_log.rs # Audit log entries
│ ├── handlers/
│ │ ├── mod.rs # Handler re-exports
│ │ ├── auth.rs # Login, register, password reset
│ │ ├── profile.rs # User profile (self)
│ │ ├── contents.rs # Public content by slug
│ │ ├── menus.rs # Public menu fetch
│ │ ├── lookups.rs # Public lookup data
│ │ └── admin/
│ │ ├── mod.rs # Admin handler re-exports
│ │ ├── users.rs # User CRUD
│ │ ├── roles.rs # Role CRUD
│ │ ├── permissions.rs # Permission listing
│ │ ├── contents.rs # Content CRUD
│ │ ├── menus.rs # Menu CRUD
│ │ ├── media.rs # Media upload/management
│ │ ├── lookups.rs # Lookup CRUD
│ │ ├── settings.rs # App settings
│ │ └── audit_logs.rs # Audit log viewer
│ ├── services/
│ │ ├── mod.rs # Service re-exports
│ │ ├── auth.rs # Auth business logic
│ │ ├── content.rs # Content business logic
│ │ ├── menu.rs # Menu business logic
│ │ ├── media.rs # File handling
│ │ └── lookup.rs # Lookup business logic
│ ├── dto/
│ │ ├── mod.rs # DTO re-exports
│ │ ├── common.rs # Shared types (pagination, responses)
│ │ ├── auth.rs # Auth request/response types
│ │ ├── user.rs # User DTOs
│ │ ├── role.rs # Role DTOs
│ │ ├── content.rs # Content DTOs
│ │ ├── menu.rs # Menu DTOs
│ │ └── lookup.rs # Lookup DTOs
│ ├── middleware/
│ │ ├── mod.rs # Middleware re-exports
│ │ ├── auth.rs # JWT extraction and validation
│ │ ├── rbac.rs # Permission-based access control
│ │ └── request_id.rs # Request ID injection
│ ├── routes/
│ │ ├── mod.rs # Route registration (public + admin)
│ │ ├── auth.rs # Auth route group
│ │ ├── public.rs # Public API routes
│ │ └── admin.rs # Admin API routes (protected)
│ ├── docs/
│ │ └── mod.rs # OpenAPI spec generation (utoipa)
│ └── utils/
│ ├── mod.rs # Utility re-exports
│ ├── response.rs # Standardized JSON responses
│ ├── pagination.rs # Pagination helpers
│ └── validation.rs # Input validation helpers
├── migrations/ # SQL migration files
│ ├── 00001_create_users_table.sql
│ ├── 00002_create_roles_table.sql
│ ├── 00003_create_permissions_table.sql
│ ├── 00004_create_role_permissions_table.sql
│ ├── ...
│ ├── 00014_create_contents_table.sql
│ ├── 00015_create_menus_table.sql
│ └── 00017_create_lookups_table.sql
└── seeders/ # SQL seed files
├── 01_roles.sql
├── 02_permissions.sql
├── 03_users.sql
├── 04_role_permissions.sql
├── 05_user_roles.sql
└── 06_translations.sqlنصيحة — المعمارية الطبقية
تتبع الخلفية دورة حياة طلب واضحة: المسارات تُعرّف نقاط النهاية، البرمجيات الوسيطة تفرض المصادقة والصلاحيات، المعالجات تحلل الطلبات وتعيد الاستجابات، الخدمات تحتوي منطق الأعمال، النماذج تتفاعل مع قاعدة البيانات، وكائنات نقل البيانات تُحدد أشكال البيانات العابرة للحدود.
الملفات الرئيسية
| الملف | الغرض |
|---|---|
main.rs | يُهيّئ خادم Axum، ويتصل بقاعدة البيانات وRedis، ويُسجّل جميع المسارات |
config/*.rs | يقرأ متغيرات البيئة وforge.yaml في هياكل إعدادات مُنمّطة |
middleware/auth.rs | يستخرج ويتحقق من رموز JWT من ترويسة Authorization |
middleware/rbac.rs | يفحص صلاحيات المستخدم المُصادق مقابل الصلاحية المطلوبة للمسار |
docs/mod.rs | يُنشئ مواصفات OpenAPI المُقدّمة على /docs |
تطبيق الويب (apps/web/)
تطبيق Next.js العام مع App Router:
apps/web/
├── package.json
├── next.config.js
├── tailwind.config.ts
├── tsconfig.json
├── .env.local # Frontend environment variables
├── public/ # Static assets
│ ├── favicon.ico
│ └── images/
├── app/
│ ├── layout.tsx # Root layout (HTML, fonts, providers)
│ ├── page.tsx # Homepage
│ ├── [slug]/
│ │ └── page.tsx # Dynamic CMS content pages
│ ├── (auth)/
│ │ ├── login/
│ │ │ └── page.tsx # Login page
│ │ ├── register/
│ │ │ └── page.tsx # Registration page
│ │ └── forgot-password/
│ │ └── page.tsx # Password reset
│ └── (protected)/
│ ├── layout.tsx # Auth-protected layout
│ └── profile/
│ └── page.tsx # Profile page
├── components/
│ ├── ui/ # Base shadcn/ui components
│ │ ├── button.tsx
│ │ ├── input.tsx
│ │ ├── card.tsx
│ │ └── ...
│ ├── providers/
│ │ ├── query-provider.tsx # TanStack Query provider
│ │ └── i18n-provider.tsx # i18n provider
│ ├── site-header.tsx # Site header with navigation
│ ├── site-footer.tsx # Site footer
│ ├── dynamic-nav.tsx # Dynamic nav from menus API
│ └── language-switcher.tsx # Language/locale switcher
└── lib/
├── api.ts # API client (fetch wrapper)
├── auth.ts # Auth utilities (token management)
├── types.ts # TypeScript type definitions
└── utils.ts # Shared helper functionsمجموعات المسارات
يستخدم تطبيق الويب مجموعات المسارات في Next.js لتنظيم الصفحات:
| المجموعة | المسار | الغرض |
|---|---|---|
(auth) | /login، /register، /forgot-password | صفحات المصادقة — تعيد التوجيه إذا كان المستخدم مسجّلاً بالفعل |
(protected) | /profile | تتطلب مصادقة — تعيد التوجيه لتسجيل الدخول إذا لم يكن مُصادقاً |
[slug] | /:slug | صفحات نظام إدارة المحتوى الديناميكية — تجلب المحتوى بالمسار من الواجهة البرمجية |
تطبيق الإدارة (apps/admin/)
لوحة الإدارة هي تطبيق Next.js منفصل مع واجهات CRUD كاملة:
apps/admin/
├── package.json
├── next.config.js
├── tailwind.config.ts
├── tsconfig.json
├── .env.local
├── app/
│ ├── layout.tsx # Root layout
│ ├── (auth)/
│ │ └── login/
│ │ └── page.tsx # Admin login page
│ └── (dashboard)/
│ ├── layout.tsx # Dashboard layout (sidebar + header)
│ ├── page.tsx # Dashboard home (overview)
│ ├── users/
│ │ ├── page.tsx # Users list (paginated, searchable)
│ │ ├── create/
│ │ │ └── page.tsx # Create user form
│ │ └── [id]/
│ │ ├── page.tsx # User detail view
│ │ └── edit/
│ │ └── page.tsx # Edit user form
│ ├── roles/
│ │ ├── page.tsx # Roles list
│ │ ├── create/
│ │ │ └── page.tsx # Create role with permissions
│ │ └── [id]/
│ │ └── edit/
│ │ └── page.tsx # Edit role
│ ├── contents/
│ │ ├── page.tsx # Content pages list
│ │ ├── create/
│ │ │ └── page.tsx # Rich text content editor
│ │ └── [id]/
│ │ ├── page.tsx # View content
│ │ └── edit/
│ │ └── page.tsx # Edit content
│ ├── menus/
│ │ ├── page.tsx # Menus list
│ │ ├── create/
│ │ │ └── page.tsx # Create menu with items
│ │ └── [id]/
│ │ └── edit/
│ │ └── page.tsx # Edit menu
│ ├── lookups/
│ │ ├── page.tsx # Lookup tables list
│ │ └── [id]/
│ │ └── page.tsx # Lookup table entries
│ ├── media/
│ │ └── page.tsx # Media library
│ ├── settings/
│ │ └── page.tsx # Application settings
│ └── audit-logs/
│ └── page.tsx # Audit log viewer
├── components/
│ ├── ui/ # shadcn/ui components
│ ├── layout/
│ │ ├── sidebar.tsx # Collapsible sidebar nav
│ │ ├── header.tsx # Top header with user menu
│ │ └── breadcrumbs.tsx # Dynamic breadcrumb nav
│ ├── providers/
│ │ ├── query-provider.tsx
│ │ └── i18n-provider.tsx
│ ├── data-table.tsx # Reusable data table component
│ ├── rich-text-editor.tsx # Content editor (TipTap)
│ └── media-picker.tsx # Media selection dialog
└── lib/
├── api.ts # Admin API client
├── auth.ts # Admin auth utilities
├── types.ts # Admin TypeScript types
└── utils.ts # Admin utilitiesمعلومة — لوحة الإدارة تتبع أنماط CRUD
كل مورد في لوحة الإدارة يتبع نفس النمط: قائمة -> إنشاء -> عرض -> تعديل. هذا التناسق يجعل كود الإدارة متوقعاً وسهل التوسيع عند إضافة ميزات جديدة.
البنية التحتية (infra/)
إعدادات البنية التحتية للتطوير المحلي والنشر:
infra/
├── docker/
│ ├── docker-compose.yml # Service definitions (PostgreSQL, Redis, Caddy)
│ ├── docker-compose.dev.yml # Development overrides
│ ├── docker-compose.prod.yml # Production overrides
│ ├── Dockerfile.api # Multi-stage Rust build
│ ├── Dockerfile.web # Next.js web build
│ └── Dockerfile.admin # Next.js admin build
├── caddy/
│ └── Caddyfile # Reverse proxy config + HTTPS
└── certs/
├── myapp.test.pem # SSL certificate (generated by mkcert)
└── myapp.test-key.pem # SSL private keyإعدادات Caddy
يوجّه ملف Caddyfile الطلبات إلى التطبيق الصحيح:
caddyfile
myapp.test {
reverse_proxy localhost:3001 # → Next.js web app
tls /etc/caddy/certs/myapp.test.pem /etc/caddy/certs/myapp.test-key.pem
}
admin.myapp.test {
reverse_proxy localhost:3002 # → Next.js admin app
tls /etc/caddy/certs/myapp.test.pem /etc/caddy/certs/myapp.test-key.pem
}
api.myapp.test {
reverse_proxy localhost:3000 # → Rust API server
tls /etc/caddy/certs/myapp.test.pem /etc/caddy/certs/myapp.test-key.pem
}قاعدة البيانات (database/)
ملفات إدارة قاعدة البيانات التي تقع خارج تطبيق الواجهة البرمجية للوضوح:
database/
├── migrations/ # Ordered SQL migration files
│ ├── 00001_create_users_table.sql
│ ├── 00002_create_roles_table.sql
│ ├── 00003_create_permissions_table.sql
│ ├── 00004_create_role_permissions_table.sql
│ ├── 00005_create_user_roles_table.sql
│ ├── 00006_create_settings_table.sql
│ ├── 00007_create_audit_logs_table.sql
│ ├── 00008_create_api_keys_table.sql
│ ├── 00009_create_password_resets_table.sql
│ ├── 00010_create_refresh_tokens_table.sql
│ ├── 00011_create_media_table.sql
│ ├── 00012_create_translations_table.sql
│ ├── 00013_create_notifications_table.sql
│ ├── 00014_create_contents_table.sql
│ ├── 00015_create_menus_table.sql
│ └── 00017_create_lookups_table.sql
└── seeders/
├── 01_roles.sql # Default roles (super_admin, admin, user)
├── 02_permissions.sql # All system permissions
├── 03_users.sql # Default admin user
├── 04_role_permissions.sql # Role-permission assignments
├── 05_user_roles.sql # Admin user role assignment
└── 06_translations.sql # Default UI translationsتنبيه — ترتيب الترحيلات مهم
تُنفّذ الترحيلات بالترتيب الرقمي. يستخدم FORGE بادئات من خمسة أرقام مُبطّنة بالأصفار (مثل 00001، 00002) لضمان الترتيب الصحيح. عند إضافة ترحيلات مخصصة، استخدم الرقم التالي المتاح أو شغّل forge make:migration للتعيين التلقائي.
ملف forge.yaml
ملف بيان المشروع في جذر مشروعك. يقرأه FORGE لجميع العمليات — توليد الأكواد، والترحيلات، وإعداد مزودي الخدمات، والنشر. انظر صفحة الإعدادات للمرجع الكامل.
الخطوات التالية
الآن بعد أن فهمت تخطيط المشروع، تعمّق في مناطق محددة:
- نظرة عامة على الخلفية — تعرّف على بنية واجهة Rust البرمجية وكيفية توسيعها
- نظرة عامة على الواجهة الأمامية — استكشف تطبيقات Next.js بالتفصيل
- التصميم بالعقود أولاً — افهم المعمارية التي تجعل FORGE قابلاً للتوسيع
- نظام القوالب — تعرّف على كيفية توليد قوالب Tera لمشروعك