From 0122b1e6de21aaf01743002570289583b5f53fd8 Mon Sep 17 00:00:00 2001 From: Samir Boulahtit Date: Sun, 19 Oct 2025 16:07:48 +0200 Subject: [PATCH] Update project structure --- ...pdated_complete_project_structure_final.md | 263 ++++++++++++------ 1 file changed, 185 insertions(+), 78 deletions(-) diff --git a/14.updated_complete_project_structure_final.md b/14.updated_complete_project_structure_final.md index 55fcfe54..d1aa9571 100644 --- a/14.updated_complete_project_structure_final.md +++ b/14.updated_complete_project_structure_final.md @@ -7,7 +7,7 @@ This document outlines the complete project structure for a production-ready mul ## Technology Stack - **Backend**: Python FastAPI with PostgreSQL -- **Frontend**: Vanilla HTML, CSS, JavaScript with AJAX +- **Frontend**: Vanilla HTML, CSS, JavaScript with Alpine.js (CDN-based, no build step) - **Background Jobs**: Celery with Redis - **Search**: Elasticsearch with database fallback - **Caching**: Redis multi-layer caching @@ -21,30 +21,33 @@ This document outlines the complete project structure for a production-ready mul ├── main.py # FastAPI application entry point ├── app/ │ ├── api/ -│ │ ├── deps.py # Common dependencies +│ │ ├── deps.py # Common dependencies (auth, context) │ │ ├── main.py # API router setup │ │ └── v1/ # API version 1 routes │ │ ├── admin/ # Super admin endpoints -│ │ │ ├── __init__.py +│ │ │ ├── __init__.py # Admin router aggregation │ │ │ ├── auth.py # Admin authentication -│ │ │ ├── vendors.py # Vendor management (CRUD, bulk import) +│ │ │ ├── vendors.py # Vendor management (CRUD, bulk operations) │ │ │ ├── dashboard.py # Admin dashboard & statistics │ │ │ ├── users.py # User management across vendors │ │ │ ├── marketplace.py # System-wide marketplace monitoring -│ │ │ └── monitoring.py # Platform monitoring & alerts +│ │ │ ├── audit.py # Audit log endpoints +│ │ │ ├── settings.py # Platform settings management +│ │ │ ├── notifications.py # Admin notifications & alerts +│ │ │ └── monitoring.py # Platform monitoring & health checks │ │ ├── vendor/ # Vendor-scoped endpoints │ │ │ ├── __init__.py │ │ │ ├── auth.py # Vendor team authentication │ │ │ ├── dashboard.py # Vendor dashboard & statistics │ │ │ ├── products.py # Vendor catalog management (Product table) -│ │ │ ├── marketplace.py # Marketplace import & selection (MarketplaceProduct table) +│ │ │ ├── marketplace.py # Marketplace import & selection (MarketplaceProduct) │ │ │ ├── orders.py # Vendor order management │ │ │ ├── customers.py # Vendor customer management │ │ │ ├── teams.py # Team member management -│ │ │ ├── inventory.py # Inventory operations (vendor catalog products) +│ │ │ ├── inventory.py # Inventory operations (vendor catalog) │ │ │ ├── payments.py # Payment configuration & processing │ │ │ ├── media.py # File and media management -│ │ │ ├── notifications.py # Notification management +│ │ │ ├── notifications.py # Vendor notification management │ │ │ └── settings.py # Vendor settings & configuration │ │ ├── public/ # Public customer-facing endpoints │ │ │ ├── __init__.py @@ -63,6 +66,7 @@ This document outlines the complete project structure for a production-ready mul │ ├── core/ │ │ ├── config.py # Configuration settings │ │ ├── database.py # Database setup +│ │ ├── security.py # Security utilities (JWT, passwords) │ │ └── lifespan.py # App lifecycle management │ ├── exceptions/ # Custom exception handling │ │ ├── __init__.py # All exception exports @@ -85,11 +89,13 @@ This document outlines the complete project structure for a production-ready mul │ │ └── backup.py # Backup/recovery exceptions │ └── services/ # Business logic layer │ ├── auth_service.py # Authentication/authorization services -│ ├── admin_service.py # Admin services +│ ├── admin_service.py # Admin services (vendor/user management) +│ ├── admin_audit_service.py # Audit logging services +│ ├── admin_settings_service.py # Platform settings services │ ├── vendor_service.py # Vendor management services │ ├── customer_service.py # Customer services (vendor-scoped) │ ├── team_service.py # Team management services -│ ├── marketplace_service.py # Marketplace import services (MarketplaceProduct) +│ ├── marketplace_service.py # Marketplace import services │ ├── marketplace_product_service.py # Marketplace staging services │ ├── product_service.py # Vendor catalog services (Product) │ ├── order_service.py # Order services (vendor-scoped) @@ -99,7 +105,6 @@ This document outlines the complete project structure for a production-ready mul │ ├── notification_service.py # Email/notification services │ ├── search_service.py # Search and indexing services │ ├── cache_service.py # Caching services -│ ├── audit_service.py # Audit logging services │ ├── monitoring_service.py # Application monitoring services │ ├── backup_service.py # Backup and recovery services │ ├── configuration_service.py # Configuration management services @@ -117,7 +122,7 @@ This document outlines the complete project structure for a production-ready mul ├── models/ │ ├── database/ # SQLAlchemy ORM models │ │ ├── __init__.py # Import all models for easy access -│ │ ├── base.py # Base model class and common mixins +│ │ ├── base.py # Base model class and common mixins (TimestampMixin) │ │ ├── user.py # User model (with vendor relationships) │ │ ├── vendor.py # Vendor, VendorUser, Role models │ │ ├── customer.py # Customer, CustomerAddress models (vendor-scoped) @@ -128,14 +133,19 @@ This document outlines the complete project structure for a production-ready mul │ │ ├── inventory.py # Inventory, InventoryMovement models (catalog products) │ │ ├── marketplace.py # MarketplaceImportJob model │ │ ├── media.py # MediaFile, ProductMedia models -│ │ ├── notification.py # NotificationTemplate, NotificationQueue, NotificationLog models +│ │ ├── notification.py # NotificationTemplate, NotificationQueue, NotificationLog │ │ ├── search.py # SearchIndex, SearchQuery models │ │ ├── audit.py # AuditLog, DataExportLog models │ │ ├── monitoring.py # PerformanceMetric, ErrorLog, SystemAlert models │ │ ├── backup.py # BackupLog, RestoreLog models │ │ ├── configuration.py # PlatformConfig, VendorConfig, FeatureFlag models │ │ ├── task.py # TaskLog model -│ │ └── admin.py # Admin-specific models +│ │ └── admin.py # Admin-specific models +│ │ # - AdminAuditLog: Track all admin actions +│ │ # - AdminNotification: System alerts for admins +│ │ # - AdminSetting: Platform-wide settings +│ │ # - PlatformAlert: System health alerts +│ │ # - AdminSession: Admin login session tracking │ └── schema/ # Pydantic models for API validation │ ├── __init__.py # Common imports │ ├── base.py # Base Pydantic models @@ -153,7 +163,14 @@ This document outlines the complete project structure for a production-ready mul │ ├── notification.py # Notification models │ ├── search.py # Search models │ ├── monitoring.py # Monitoring models -│ ├── admin.py # Admin operation models +│ ├── admin.py # Admin operation models +│ │ # - AdminAuditLog schemas (Response, Filters, List) +│ │ # - AdminNotification schemas (Create, Response, Update, List) +│ │ # - AdminSetting schemas (Create, Response, Update, List) +│ │ # - PlatformAlert schemas (Create, Response, Resolve, List) +│ │ # - BulkOperation schemas (BulkVendorAction, BulkUserAction) +│ │ # - AdminDashboardStats, SystemHealthResponse +│ │ # - AdminSession schemas │ └── stats.py # Statistics response models ├── middleware/ │ ├── auth.py # JWT authentication @@ -165,17 +182,20 @@ This document outlines the complete project structure for a production-ready mul │ ├── __init__.py │ ├── backends.py # Storage backend implementations │ └── utils.py # Storage utilities -├── static/ # Frontend assets +├── static/ # Frontend assets (No build step!) │ ├── admin/ # Super admin interface │ │ ├── login.html # Admin login page │ │ ├── dashboard.html # Admin dashboard │ │ ├── vendors.html # Vendor management │ │ ├── users.html # User management │ │ ├── marketplace.html # System-wide marketplace monitoring +│ │ ├── audit_logs.html # Audit log viewer (NEW - TO CREATE) +│ │ ├── settings.html # Platform settings (NEW - TO CREATE) +│ │ ├── notifications.html # Admin notifications (NEW - TO CREATE) │ │ └── monitoring.html # System monitoring │ ├── vendor/ # Vendor admin interface -│ │ ├── login.html # Vendor team login -│ │ ├── dashboard.html # Vendor dashboard +│ │ ├── login.html # Vendor team login (TO COMPLETE) +│ │ ├── dashboard.html # Vendor dashboard (TO COMPLETE) │ │ └── admin/ # Vendor admin pages │ │ ├── products.html # Catalog management (Product table) │ │ ├── marketplace/ # Marketplace integration @@ -206,30 +226,37 @@ This document outlines the complete project structure for a production-ready mul │ │ └── addresses.html # Address management │ ├── css/ │ │ ├── admin/ # Admin interface styles +│ │ │ └── admin.css │ │ ├── vendor/ # Vendor interface styles +│ │ │ └── vendor.css │ │ ├── shop/ # Customer shop styles -│ │ ├── shared/ # Common styles -│ │ └── themes/ # Vendor-specific themes +│ │ │ └── shop.css +│ │ ├── shared/ # Common styles (base.css, auth.css) +│ │ │ ├── base.css # CSS variables, utility classes +│ │ │ └── auth.css # Login/auth page styles +│ │ └── themes/ # Vendor-specific themes (future) │ └── js/ │ ├── shared/ # Common JavaScript utilities │ │ ├── vendor-context.js # Vendor context detection & management │ │ ├── api-client.js # API communication utilities │ │ ├── notification.js # Notification handling │ │ ├── media-upload.js # File upload utilities -│ │ └── search.js # Search functionality -│ ├── admin/ # Admin interface scripts +│ │ └── utils.js # General utilities +│ ├── admin/ # Admin interface scripts (Alpine.js components) │ │ ├── dashboard.js # Admin dashboard │ │ ├── vendors.js # Vendor management +│ │ ├── audit-logs.js # Audit log viewer (NEW - TO CREATE) +│ │ ├── settings.js # Platform settings (NEW - TO CREATE) │ │ ├── monitoring.js # System monitoring │ │ └── analytics.js # Admin analytics -│ ├── vendor/ # Vendor interface scripts +│ ├── vendor/ # Vendor interface scripts (Alpine.js components) │ │ ├── products.js # Catalog management │ │ ├── marketplace.js # Marketplace integration │ │ ├── orders.js # Order management │ │ ├── payments.js # Payment configuration │ │ ├── media.js # Media management │ │ └── dashboard.js # Vendor dashboard -│ └── shop/ # Customer shop scripts +│ └── shop/ # Customer shop scripts (Alpine.js components) │ ├── catalog.js # Product browsing │ ├── search.js # Product search │ ├── cart.js # Shopping cart @@ -238,31 +265,38 @@ This document outlines the complete project structure for a production-ready mul ├── tests/ # Comprehensive test suite │ ├── unit/ # Unit tests │ │ ├── services/ # Service layer tests -│ │ │ ├── test_marketplace_service.py # Marketplace staging tests -│ │ │ ├── test_product_service.py # Catalog management tests -│ │ │ ├── test_payment_service.py # Payment processing tests -│ │ │ ├── test_notification_service.py # Notification tests -│ │ │ ├── test_search_service.py # Search functionality tests -│ │ │ ├── test_media_service.py # Media management tests -│ │ │ └── test_cache_service.py # Caching tests +│ │ │ ├── test_admin_service.py +│ │ │ ├── test_admin_audit_service.py # NEW +│ │ │ ├── test_admin_settings_service.py # NEW +│ │ │ ├── test_marketplace_service.py +│ │ │ ├── test_product_service.py +│ │ │ ├── test_payment_service.py +│ │ │ ├── test_notification_service.py +│ │ │ ├── test_search_service.py +│ │ │ ├── test_media_service.py +│ │ │ └── test_cache_service.py │ │ ├── models/ # Model tests -│ │ │ ├── test_marketplace_product.py # Staging model tests -│ │ │ ├── test_product.py # Catalog model tests -│ │ │ ├── test_payment.py # Payment model tests -│ │ │ └── test_vendor.py # Vendor model tests +│ │ │ ├── test_admin_models.py # NEW +│ │ │ ├── test_marketplace_product.py +│ │ │ ├── test_product.py +│ │ │ ├── test_payment.py +│ │ │ └── test_vendor.py │ │ └── api/ # API endpoint tests -│ │ ├── test_admin_api.py # Admin API tests -│ │ ├── test_vendor_api.py # Vendor API tests -│ │ └── test_public_api.py # Public API tests +│ │ ├── test_admin_api.py +│ │ ├── test_admin_audit_api.py # NEW +│ │ ├── test_admin_settings_api.py # NEW +│ │ ├── test_vendor_api.py +│ │ └── test_public_api.py │ ├── integration/ # Integration tests -│ │ ├── test_marketplace_workflow.py # End-to-end import workflow -│ │ ├── test_order_workflow.py # Complete order process -│ │ ├── test_payment_workflow.py # Payment processing -│ │ └── test_notification_workflow.py # Notification sending +│ │ ├── test_marketplace_workflow.py +│ │ ├── test_order_workflow.py +│ │ ├── test_payment_workflow.py +│ │ ├── test_audit_workflow.py # NEW +│ │ └── test_notification_workflow.py │ ├── e2e/ # End-to-end tests -│ │ ├── test_vendor_onboarding.py # Complete vendor setup -│ │ ├── test_customer_journey.py # Customer shopping experience -│ │ └── test_admin_operations.py # Admin platform management +│ │ ├── test_vendor_onboarding.py +│ │ ├── test_customer_journey.py +│ │ └── test_admin_operations.py │ └── fixtures/ # Test data fixtures │ ├── marketplace_data.py # Sample marketplace import data │ ├── catalog_data.py # Sample vendor catalog data @@ -271,6 +305,7 @@ This document outlines the complete project structure for a production-ready mul ├── scripts/ # Utility scripts │ ├── init_db.py # Database initialization │ ├── create_admin.py # Create initial admin user +│ ├── init_platform_settings.py # Create default platform settings │ ├── backup_database.py # Manual backup script │ ├── seed_data.py # Development data seeding │ └── migrate_data.py # Data migration utilities @@ -280,10 +315,23 @@ This document outlines the complete project structure for a production-ready mul │ ├── docker-compose.prod.yml # Production environment │ └── nginx.conf # Nginx configuration ├── docs/ # Documentation +│ ├── slices/ # Vertical slice documentation +│ │ ├── 00_slices_overview.md +│ │ ├── 00_implementation_roadmap.md +│ │ ├── 01_slice1_admin_vendor_foundation.md +│ │ ├── 02_slice2_marketplace_import.md +│ │ ├── 03_slice3_product_catalog.md +│ │ ├── 04_slice4_customer_shopping.md +│ │ └── 05_slice5_order_processing.md │ ├── api/ # API documentation │ ├── deployment/ # Deployment guides │ ├── development/ # Development setup -│ └── user_guides/ # User manuals +│ ├── user_guides/ # User manuals +│ ├── 6.complete_naming_convention.md +│ ├── 10.stripe_payment_integration.md +│ ├── 12.project_readme_final.md +│ ├── 13.updated_application_workflows_final.md +│ └── 14.updated_complete_project_structure_final.md ├── .env.example # Environment variables template ├── requirements.txt # Python dependencies ├── requirements-dev.txt # Development dependencies @@ -291,6 +339,62 @@ This document outlines the complete project structure for a production-ready mul └── DEPLOYMENT.md # Deployment instructions ``` +## Key Changes from Previous Version + +### Admin Infrastructure + +**Database Models** (`models/database/admin.py`): +- ✅ `AdminAuditLog` - Complete audit trail of all admin actions +- ✅ `AdminNotification` - System notifications for admins +- ✅ `AdminSetting` - Platform-wide configuration with encryption support +- ✅ `PlatformAlert` - System health and issue tracking +- ✅ `AdminSession` - Admin login session tracking + +**Pydantic Schemas** (`models/schema/admin.py`): +- ✅ Comprehensive request/response models for all admin operations +- ✅ Filtering and pagination schemas +- ✅ Bulk operation schemas (vendor/user actions) +- ✅ System health monitoring schemas + +**Services**: +- ✅ `admin_audit_service.py` - Audit logging functionality +- ✅ `admin_settings_service.py` - Platform settings with type conversion + +**API Endpoints**: +- ✅ `/api/v1/admin/audit/*` - Audit log querying and filtering +- ✅ `/api/v1/admin/settings/*` - Settings CRUD operations +- ✅ `/api/v1/admin/notifications/*` - Notifications & alerts (structure ready) + +### Naming Convention Fixes +- ✅ Changed `models/schemas/` to `models/schema/` (singular) +- ✅ All schema files now consistently use singular naming + +### Current Development Status (Slice 1) + +**Completed (✅)**: +- Backend database models (User, Vendor, Role, VendorUser, Admin models) +- JWT authentication with bcrypt +- Admin service layer with audit logging capability +- Admin API endpoints (CRUD, dashboard, audit, settings) +- Vendor context middleware +- Admin login page (Alpine.js) +- Admin dashboard (Alpine.js) +- Admin vendor creation page (Alpine.js) + +**In Progress (⏳)**: +- Vendor login page (frontend) +- Vendor dashboard page (frontend) +- Admin audit logs page (frontend) +- Admin platform settings page (frontend) + +**To Do (📋)**: +- Complete vendor login/dashboard pages +- Integrate audit logging into existing admin operations +- Create admin audit logs frontend +- Create platform settings frontend +- Full testing of Slice 1 +- Deployment to staging + ## Architecture Principles ### Multi-Tenancy Model @@ -303,25 +407,28 @@ This document outlines the complete project structure for a production-ready mul ``` Marketplace CSV → MarketplaceProduct (staging) → Product (catalog) → Order → Analytics ↓ - Email Notifications → Audit Logs → Monitoring + Admin Audit Logs → Platform Settings → Notifications → Monitoring ``` ### API Structure - **Admin APIs** (`/api/v1/admin/`): Platform-level administration + - Vendor management, user management, audit logs, settings, alerts - **Vendor APIs** (`/api/v1/vendor/`): Vendor-scoped operations (requires vendor context) + - Products, orders, customers, teams, marketplace integration - **Public APIs** (`/api/v1/public/vendors/{vendor_id}/`): Customer-facing operations + - Shop, products, cart, orders, checkout - **Shared APIs** (`/api/v1/shared/`): Utility endpoints (health, webhooks) ### Service Layer Architecture -- **Domain Services**: Each service handles one business domain (products, orders, payments) -- **Cross-Cutting Services**: Shared services (cache, audit, monitoring, notifications) -- **Integration Services**: External service integration (payments, search, storage) +- **Domain Services**: Each service handles one business domain +- **Cross-Cutting Services**: Audit, cache, monitoring, notifications +- **Integration Services**: Payments, search, storage ### Frontend Architecture -- **Static Assets**: All frontend files served from `/static/` directory -- **Single Application**: One frontend codebase serving all vendors -- **Context-Aware Routing**: Automatic vendor detection via subdomain or path -- **Dynamic Theming**: Vendor-specific customization and branding +- **Zero Build Step**: Alpine.js from CDN, vanilla CSS, no compilation +- **Server-Side Rendering**: Jinja2 templates with Alpine.js enhancement +- **Context-Aware**: Automatic vendor detection via subdomain or path +- **Dynamic Theming**: Vendor-specific customization via CSS variables - **Role-Based UI**: Permission-driven interface elements ## Key Features @@ -360,22 +467,6 @@ Marketplace CSV → MarketplaceProduct (staging) → Product (catalog) → Order - Email providers (SendGrid, SMTP) - Monitoring and alerting systems -## Deployment Modes - -### Development Mode -- **Path-based routing**: `localhost:3000/vendor/vendorname/` -- **Admin access**: `localhost:3000/admin/` -- **Easy context switching**: Clear vendor separation in URLs -- **Local storage**: Files stored locally with hot reload - -### Production Mode -- **Subdomain routing**: `vendorname.platform.com` -- **Admin subdomain**: `admin.platform.com` -- **Custom domains**: `customdomain.com` (enterprise feature) -- **CDN integration**: Optimized asset delivery -- **Distributed caching**: Redis cluster for performance -- **Automated backups**: Scheduled database and file backups - ## Technology Integration ### Database Layer @@ -389,15 +480,31 @@ Marketplace CSV → MarketplaceProduct (staging) → Product (catalog) → Order - **Monitoring**: Task progress and error tracking ### External Services -- **Stripe Connect**: Payment processing -- **SendGrid/SMTP**: Email delivery -- **AWS S3/GCS**: Cloud storage -- **CloudFront/CloudFlare**: CDN +- **Stripe Connect**: Multi-vendor payment processing +- **SendGrid/SMTP**: Email delivery with vendor branding +- **AWS S3/GCS**: Cloud storage for media files +- **CloudFront/CloudFlare**: CDN for static assets -### Monitoring Stack -- **Custom Monitoring**: Application-specific metrics +### Monitoring & Compliance +- **Admin Audit Logs**: Complete trail of all admin actions +- **Platform Settings**: Centralized configuration management +- **System Alerts**: Automated health monitoring - **Error Tracking**: Comprehensive error logging -- **Performance Monitoring**: Response times and throughput -- **Health Checks**: Automated system health monitoring + +## Deployment Modes + +### Development Mode +- **Path-based routing**: `localhost:8000/vendor/vendorname/` +- **Admin access**: `localhost:8000/admin/` +- **Easy context switching**: Clear vendor separation in URLs +- **Local storage**: Files stored locally with hot reload + +### Production Mode +- **Subdomain routing**: `vendorname.platform.com` +- **Admin subdomain**: `admin.platform.com` +- **Custom domains**: `customdomain.com` (enterprise feature) +- **CDN integration**: Optimized asset delivery +- **Distributed caching**: Redis cluster for performance +- **Automated backups**: Scheduled database and file backups This structure provides a robust foundation for a scalable, multi-tenant ecommerce platform with enterprise-grade features while maintaining clean separation of concerns and supporting multiple deployment modes. \ No newline at end of file