docs: update architecture docs with JS module organization

Update frontend-structure.md: - Add "Module Static Files" section explaining the new organization - Document how module static files are served (/static/modules/{module}/) - Add table showing which JS files belong to which module - Explain platform vs module static file distinction - Document user type distinction (admin users vs platform users vs customers) Update module-system.md: - Expand static directory structure example - Add "Module Static Files" section with referencing examples - Add table for module vs platform static file decisions - Cross-reference to frontend-structure.md for details Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-30 22:25:13 +01:00
parent baf70d6eb1
commit aebc309738
2 changed files with 156 additions and 3 deletions
--- a/docs/architecture/frontend-structure.md
+++ b/docs/architecture/frontend-structure.md
@@ -276,6 +276,120 @@ Shop product carousel → static/shop/js/carousel.js

 ---

+## Module Static Files
+
+Since January 2026, **module-specific JavaScript** is organized within each module's directory. This keeps modules self-contained and follows the plug-and-play architecture.
+
+### Directory Structure
+
+```
+app/modules/{module}/static/
+├── admin/js/           # Admin pages for this module
+├── vendor/js/          # Vendor pages for this module
+├── shared/js/          # Shared across admin/vendor for this module
+└── shop/js/            # Shop pages for this module (if applicable)
+```
+
+### How Module Static Files Are Served
+
+Module static files are mounted at `/static/modules/{module_name}/`:
+
+```python
+# In main.py (automatic for all modules with static/ directory)
+app.mount("/static/modules/orders", StaticFiles(directory="app/modules/orders/static"))
+```
+
+### Referencing Module Static Files
+
+**In templates, use the `{module}_static` URL name:**
+
+```html
+<!-- Orders module JS -->
+<script src="{{ url_for('orders_static', path='admin/js/orders.js') }}"></script>
+<script src="{{ url_for('orders_static', path='vendor/js/order-detail.js') }}"></script>
+
+<!-- Billing module JS (includes shared feature-store) -->
+<script src="{{ url_for('billing_static', path='shared/js/feature-store.js') }}"></script>
+<script src="{{ url_for('billing_static', path='vendor/js/billing.js') }}"></script>
+
+<!-- Marketplace module JS -->
+<script src="{{ url_for('marketplace_static', path='vendor/js/onboarding.js') }}"></script>
+```
+
+### Module vs. Platform Static Files
+
+| Location | Purpose | Example Files |
+|----------|---------|---------------|
+| `static/admin/js/` | Platform-level admin (not module-specific) | dashboard.js, login.js, platforms.js, vendors.js, admin-users.js |
+| `static/vendor/js/` | Vendor core (not module-specific) | dashboard.js, login.js, profile.js, settings.js, team.js |
+| `static/shared/js/` | Shared utilities across all frontends | api-client.js, utils.js, money.js, icons.js |
+| `app/modules/*/static/` | Module-specific functionality | orders.js, products.js, billing.js, etc. |
+
+### Current Module JS Organization
+
+| Module | Admin JS | Vendor JS | Shared JS |
+|--------|----------|-----------|-----------|
+| **orders** | orders.js | orders.js, order-detail.js | - |
+| **catalog** | products.js, product-*.js | products.js, product-create.js | - |
+| **inventory** | inventory.js | inventory.js | - |
+| **customers** | customers.js | customers.js | - |
+| **billing** | billing-history.js, subscriptions.js, subscription-tiers.js | billing.js, invoices.js | feature-store.js, upgrade-prompts.js |
+| **messaging** | messages.js, notifications.js, email-templates.js | messages.js, notifications.js, email-templates.js | - |
+| **marketplace** | marketplace*.js, letzshop*.js | letzshop.js, marketplace.js, onboarding.js | - |
+| **monitoring** | monitoring.js, background-tasks.js, imports.js, logs.js | - | - |
+| **dev_tools** | testing-*.js, code-quality-*.js | - | - |
+| **cms** | content-pages.js, content-page-edit.js | content-pages.js, content-page-edit.js | - |
+| **analytics** | - | analytics.js | - |
+
+### Platform Static Files (Not in Modules)
+
+These files remain in `static/` because they're platform-level, not module-specific:
+
+**Admin Core (`static/admin/js/`):**
+- `init-alpine.js` - Admin layout initialization
+- `dashboard.js` - Main admin dashboard
+- `login.js` - Admin authentication
+- `platforms.js`, `platform-*.js` - Platform management (6 files)
+- `vendors.js`, `vendor-*.js` - Vendor management at platform level (6 files)
+- `companies.js`, `company-*.js` - Company management (3 files)
+- `admin-users.js`, `admin-user-*.js` - Admin user management (3 files)
+- `users.js`, `user-*.js` - Platform user management (4 files)
+- `settings.js`, `components.js`, `icons-page.js` - Platform utilities
+
+**Vendor Core (`static/vendor/js/`):**
+- `init-alpine.js` - Vendor layout initialization
+- `dashboard.js` - Vendor main dashboard
+- `login.js` - Vendor authentication
+- `profile.js` - Vendor account settings
+- `settings.js` - Vendor configuration
+- `team.js` - Team member management
+- `media.js` - Media library (shared across products)
+
+**Shared Utilities (`static/shared/js/`):**
+- `api-client.js` - Core HTTP client with auth
+- `utils.js` - Date formatting, currency, toasts
+- `money.js` - Money/currency handling
+- `icons.js` - Heroicons SVG definitions
+- `log-config.js` - Centralized logging
+- `vendor-selector.js` - Vendor autocomplete component
+- `media-picker.js` - Media picker component
+
+### User Type Distinction
+
+The codebase distinguishes between three types of users:
+
+| Type | Management JS | Location | Description |
+|------|---------------|----------|-------------|
+| **Admin Users** | admin-users.js | `static/admin/js/` | Platform administrators (super admins, platform admins) |
+| **Platform Users** | users.js | `static/admin/js/` | Vendor/company users who log into the platform |
+| **Shop Customers** | customers.js | `app/modules/customers/static/` | End customers who buy from vendors |
+
+This distinction is important:
+- `admin-users.js` and `users.js` manage **internal platform users** → Stay in `static/admin/js/`
+- `customers.js` manages **shop customers** → Lives in the customers module
+
+---
+
 ## Shared Resources

 ### Templates (`app/templates/shared/`)
--- a/docs/architecture/module-system.md
+++ b/docs/architecture/module-system.md
@@ -142,9 +142,10 @@ app/modules/analytics/
 │       └── vendor/
 │           └── analytics.html
 ├── static/                  # Auto-mounted at /static/modules/analytics/
-│   └── vendor/
-│       └── js/
-│           └── analytics.js
+│   ├── admin/js/            # Admin-facing JS for this module
+│   ├── vendor/js/           # Vendor-facing JS for this module
+│   │   └── analytics.js
+│   └── shared/js/           # Shared JS (used by both admin and vendor)
 ├── locales/                 # Auto-loaded translations
 │   ├── en.json
 │   ├── de.json
@@ -349,6 +350,44 @@ module_service.enable_module(db, platform_id, "billing", user_id=current_user.id
 module_service.disable_module(db, platform_id, "billing", user_id=current_user.id)
 ```

+## Module Static Files
+
+Each module can have its own static assets (JavaScript, CSS, images) in the `static/` directory. These are automatically mounted at `/static/modules/{module_name}/`.
+
+### Static File Structure
+
+```
+app/modules/{module}/static/
+├── admin/js/           # Admin pages for this module
+├── vendor/js/          # Vendor pages for this module
+├── shared/js/          # Shared across admin/vendor (e.g., feature-store.js)
+└── shop/js/            # Shop pages (if module has storefront UI)
+```
+
+### Referencing in Templates
+
+Use the `{module}_static` URL name:
+
+```html
+<!-- Module-specific JS -->
+<script src="{{ url_for('orders_static', path='vendor/js/orders.js') }}"></script>
+<script src="{{ url_for('billing_static', path='shared/js/feature-store.js') }}"></script>
+```
+
+### Module vs. Platform Static Files
+
+| Put in Module | Put in Platform (`static/`) |
+|---------------|----------------------------|
+| Module-specific features | Platform-level admin (dashboard, login, platforms, vendors) |
+| Order management → `orders` module | Vendor core (profile, settings, team) |
+| Product catalog → `catalog` module | Shared utilities (api-client, utils, icons) |
+| Billing/subscriptions → `billing` module | Admin user management |
+| Analytics dashboards → `analytics` module | Platform user management |
+
+**Key distinction:** Platform users (admin-users.js, users.js) manage internal platform access. Shop customers (customers.js in customers module) are end-users who purchase from vendors.
+
+See [Frontend Structure](frontend-structure.md) for detailed JS file organization.
+
 ## Module Configuration

 Modules can have environment-based configuration using Pydantic Settings. The `config.py` file is auto-discovered by `app/modules/config.py`.