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