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>

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/`)