@fuzionx/framework 0.1.22 → 0.1.24

package/cli/index.js

@@ -51,16 +51,21 @@ async function loadTemplate(relativePath, vars = {}) {
 //  fx make:* — 코드 생성
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-const TYPE_DIRS = {
+/** 앱별 파일 (--app 필수) */
+const APP_TYPE_DIRS = {
     controller: 'controllers',
     service: 'services',
-    model: 'models',
     middleware: 'middleware',
-    job: 'jobs',
-    task: 'jobs',
     ws: 'ws',
-    event: 'events',
-    worker: 'workers',
+};
+
+/** 공유 파일 (앱 무관) */
+const SHARED_TYPE_DIRS = {
+    model: 'database/models',
+    job: 'shared/jobs',
+    task: 'shared/jobs',
+    event: 'shared/events',
+    worker: 'shared/workers',
     test: 'tests',
 };
 
@@ -78,15 +83,23 @@ const TYPE_SUFFIXES = {
 };
 
 /**
- * fx make:<type> <Name> — 코드 생성
+ * fx make:<type> <Name> [--app=<appName>] — 코드 생성
  * @param {string} type - 'controller', 'service', 'model', 등
  * @param {string} name - PascalCase 이름 (e.g. 'User')
  * @param {string} [baseDir='.'] - 프로젝트 루트
+ * @param {string} [appName] - 앱 이름 (controller/service/middleware/ws 시 필수)
  * @returns {Promise<string>} - 생성된 파일 경로
  */
-export async function makeFile(type, name, baseDir = '.') {
-    const dir = TYPE_DIRS[type];
-    if (!dir) throw new Error(`Unknown type: ${type}`);
+export async function makeFile(type, name, baseDir = '.', appName) {
+    let dir;
+    if (APP_TYPE_DIRS[type]) {
+        if (!appName) throw new Error(`--app option required for make:${type} (e.g. fx make:${type} ${name} --app=backend)`);
+        dir = `app/${appName}/${APP_TYPE_DIRS[type]}`;
+    } else if (SHARED_TYPE_DIRS[type]) {
+        dir = SHARED_TYPE_DIRS[type];
+    } else {
+        throw new Error(`Unknown type: ${type}`);
+    }
 
     const suffix = TYPE_SUFFIXES[type];
     const fileName = `${name}${suffix}.js`;
@@ -114,25 +127,32 @@ const APP_FILES = [
     { tpl: 'app/package.json.tpl', dest: 'package.json' },
     { tpl: 'app/fuzionx.yaml.tpl', dest: 'fuzionx.yaml' },
     { tpl: 'app/app.js.tpl', dest: 'app.js' },
-    { tpl: 'app/routes/web.js.tpl', dest: 'routes/web.js' },
-    { tpl: 'app/routes/api.js.tpl', dest: 'routes/api.js' },
+    { tpl: 'app/routes/web.js.tpl', dest: 'app/backend/routes/web.js' },
+    { tpl: 'app/routes/api.js.tpl', dest: 'app/backend/routes/api.js' },
     { tpl: 'app/.env.example.tpl', dest: '.env.example' },
     { tpl: 'app/.env.example.tpl', dest: '.env' },
     { tpl: 'app/.gitignore.tpl', dest: '.gitignore' },
 ];
 
-/** 스캐폴딩 디렉토리 (16-cli.md) */
+/** 스캐폴딩 디렉토리 (multi-app 구조) */
 const APP_DIRS = [
-    'controllers',
-    'models',
-    'services',
-    'middleware',
-    'ws',
-    'jobs',
-    'events',
-    'workers',
-    'migrations',
-    'seeds',
+    // 앱별
+    'app/backend/controllers',
+    'app/backend/routes',
+    'app/backend/services',
+    'app/backend/middleware',
+    'app/backend/views/default/pages',
+    'app/backend/views/default/layouts',
+    'app/backend/views/default/errors',
+    'app/backend/ws',
+    // 공유
+    'database/models',
+    'database/migrations',
+    'database/seeds',
+    'shared/events',
+    'shared/jobs',
+    'shared/workers',
+    // 인프라
     'storage/logs',
     'storage/uploads',
     'public/css',
@@ -156,7 +176,11 @@ export async function createApp(name, targetDir) {
     // 디렉토리 생성
     for (const d of APP_DIRS) {
         await fs.mkdir(path.join(dir, d), { recursive: true });
-        await fs.writeFile(path.join(dir, d, '.gitkeep'), '');
+        // .gitkeep 는 리프 원래 파일이 없는 디렉토리에만
+        const files = await fs.readdir(path.join(dir, d)).catch(() => []);
+        if (files.length === 0) {
+            await fs.writeFile(path.join(dir, d, '.gitkeep'), '');
+        }
     }
 
     // 템플릿 파일 생성
@@ -167,30 +191,36 @@ export async function createApp(name, targetDir) {
         await fs.writeFile(fullPath, content);
     }
 
-    // HomeController 복사 (16-cli.md)
+    // HomeController 복사
     const hcSrc = path.join(TPL_DIR, 'app/controllers/HomeController.js');
-    const hcDst = path.join(dir, 'controllers/HomeController.js');
+    const hcDst = path.join(dir, 'app/backend/controllers/HomeController.js');
     await fs.copyFile(hcSrc, hcDst);
 
-    // Views — views/{theme}/ 구조 (03, 16-cli.md)
+    // Views — app/backend/views/{theme}/ 구조
     const viewsSrc = path.join(TPL_DIR, 'app/views/default');
-    const viewsDst = path.join(dir, 'views/default');
+    const viewsDst = path.join(dir, 'app/backend/views/default');
 
     // layouts/main.html
-    const layoutDir = path.join(viewsDst, 'layouts');
-    await fs.mkdir(layoutDir, { recursive: true });
-    await fs.copyFile(path.join(viewsSrc, 'layouts/main.html'), path.join(layoutDir, 'main.html'));
+    await fs.copyFile(
+        path.join(viewsSrc, 'layouts/main.html'),
+        path.join(viewsDst, 'layouts/main.html'),
+    );
 
     // pages/home.html
-    const pagesDir = path.join(viewsDst, 'pages');
-    await fs.mkdir(pagesDir, { recursive: true });
-    await fs.copyFile(path.join(viewsSrc, 'pages/home.html'), path.join(pagesDir, 'home.html'));
+    await fs.copyFile(
+        path.join(viewsSrc, 'pages/home.html'),
+        path.join(viewsDst, 'pages/home.html'),
+    );
 
     // errors/404.html, 500.html
-    const errDir = path.join(viewsDst, 'errors');
-    await fs.mkdir(errDir, { recursive: true });
-    await fs.copyFile(path.join(viewsSrc, 'errors/404.html'), path.join(errDir, '404.html'));
-    await fs.copyFile(path.join(viewsSrc, 'errors/500.html'), path.join(errDir, '500.html'));
+    await fs.copyFile(
+        path.join(viewsSrc, 'errors/404.html'),
+        path.join(viewsDst, 'errors/404.html'),
+    );
+    await fs.copyFile(
+        path.join(viewsSrc, 'errors/500.html'),
+        path.join(viewsDst, 'errors/500.html'),
+    );
 
     return dir;
 }
@@ -220,8 +250,10 @@ export async function run(args) {
     if (command?.startsWith('make:')) {
         const type = command.replace('make:', '');
         const name = rest[0];
-        if (!name) { console.error(`Usage: fx ${command} <Name>`); process.exit(1); }
-        const file = await makeFile(type, name);
+        if (!name) { console.error(`Usage: fx ${command} <Name> [--app=<appName>]`); process.exit(1); }
+        const appFlag = rest.find(a => a.startsWith('--app='));
+        const appName = appFlag?.split('=')[1] || undefined;
+        const file = await makeFile(type, name, '.', appName);
         console.log(`✅ Created ${file}`);
         return;
     }
@@ -253,19 +285,22 @@ export async function run(args) {
         try {
             const appMod = await import(path.resolve('app.js'));
             const app = appMod.default || appMod.app;
-            if (!app?._router) { console.error('Cannot load app routes'); return; }
-            const routes = app._router.getRoutes();
+            if (!app?._appRegistry) { console.error('Cannot load app routes'); return; }
             console.log('');
-            console.log('  METHOD   PATH                  HANDLER                   MIDDLEWARE');
-            console.log('  ──────   ─────                 ────────                  ──────────');
-            for (const r of routes) {
-                const method = r.method.padEnd(8);
-                const rPath = r.path.padEnd(22);
-                const handler = r.handler?.__handler__
-                    ? `${r.handler.controller?.name || ''}.${r.handler.method}`
-                    : (typeof r.handler === 'function' ? r.handler.name || 'anonymous' : '');
-                const mw = (r.middleware || []).join(', ');
-                console.log(`  ${method} ${rPath} ${handler.padEnd(26)} ${mw}`);
+            console.log('  APP        METHOD   PATH                  HANDLER                   MIDDLEWARE');
+            console.log('  ──────     ──────   ─────                 ────────                  ──────────');
+            for (const [appName, appEntry] of app._appRegistry) {
+                const routes = appEntry.router.getRoutes();
+                for (const r of routes) {
+                    const aName = appName.padEnd(10);
+                    const method = r.method.padEnd(8);
+                    const rPath = r.path.padEnd(22);
+                    const handler = r.handler?.__handler__
+                        ? `${r.handler.controller?.name || ''}.${r.handler.method}`
+                        : (typeof r.handler === 'function' ? r.handler.name || 'anonymous' : '');
+                    const mw = (r.middleware || []).join(', ');
+                    console.log(`  ${aName} ${method} ${rPath} ${handler.padEnd(26)} ${mw}`);
+                }
             }
             console.log('');
         } catch (err) { console.error('Failed to load routes:', err.message); }
@@ -286,7 +321,7 @@ export async function run(args) {
     // ── fx db:sync — 모델 ↔ DB 스키마 diff ──
     if (command === 'db:sync') {
         try {
-            const modelsDir = path.resolve('models');
+            const modelsDir = path.resolve('database/models');
             const files = await fs.readdir(modelsDir);
             const jsFiles = files.filter(f => f.endsWith('.js'));
             console.log('\n📊 Model Schema Status:\n');
@@ -309,21 +344,21 @@ export async function run(args) {
     }
 
     console.log(`
-  fx new <name>              Create new app
-  fx make:controller <Name>  Create controller
-  fx make:service <Name>     Create service
-  fx make:model <Name>       Create model
-  fx make:middleware <Name>  Create middleware
-  fx make:job <Name>         Create job
-  fx make:task <Name>        Create task
-  fx make:ws <Name>          Create WsHandler
-  fx make:event <Name>       Create event handler
-  fx make:worker <Name>      Create worker (worker_threads)
-  fx make:test <Name>        Create test
-  fx dev                     Start dev server (--watch)
-  fx test                    Run tests
-  fx routes                  Print route table
-  fx config                  Print fuzionx.yaml
-  fx db:sync                 Sync models → DB (--apply)
+  fx new <name>                    Create new app (multi-app structure)
+  fx make:controller <Name> --app=  Create controller (app-specific)
+  fx make:service <Name> --app=     Create service (app-specific)
+  fx make:model <Name>              Create model (database/models)
+  fx make:middleware <Name> --app=   Create middleware (app-specific)
+  fx make:job <Name>                Create job (shared/jobs)
+  fx make:task <Name>               Create task (shared/jobs)
+  fx make:ws <Name> --app=          Create WsHandler (app-specific)
+  fx make:event <Name>              Create event handler (shared/events)
+  fx make:worker <Name>             Create worker (shared/workers)
+  fx make:test <Name>               Create test
+  fx dev                            Start dev server (--watch)
+  fx test                           Run tests
+  fx routes                         Print route table
+  fx config                         Print fuzionx.yaml
+  fx db:sync                        Sync models → DB (--apply)
 `);
 }

package/cli/templates/app/app.js.tpl

@@ -1,14 +1,6 @@
 import { Application } from '@fuzionx/framework';
-import webRoutes from './routes/web.js';
-import apiRoutes from './routes/api.js';
 
 const app = new Application({ configPath: './fuzionx.yaml' });
 
-app.routes(webRoutes);
-app.routes(apiRoutes);
-
 await app.boot();
-
-app.listen(49080, () => {
-    console.log('🚀 FuzionX running on http://localhost:49080');
-});
+await app.listen();

package/cli/templates/app/controllers/HomeController.js

@@ -8,6 +8,6 @@ export default class HomeController extends Controller {
 
     /** 홈 페이지 */
     async index(ctx) {
-        ctx.render('pages/home');
+        ctx.render('home');
     }
 }

package/cli/templates/app/fuzionx.yaml.tpl

@@ -1,13 +1,38 @@
 # FuzionX Configuration
 bridge:
   port: 49080
-  workers: 4
+  workers: 0
   worker_timeout: 30
 
+  cors:
+    enabled: false
+    origins:
+      - "*"
+
   rate_limit:
     enabled: true
     per_ip: 1000
 
+  session:
+    enabled: false
+    store: memory
+    ttl: 3600
+    cookie_name: fuzionx.sid
+
+  websocket:
+    enabled: false
+    path: /ws
+    check_interval: 60
+    timeout: 60
+
+  static:
+    - url: /public
+      path: ./public
+
+  logging:
+    level: info
+    intercept_console: true
+
 database:
   default: main
   connections:
@@ -18,15 +43,24 @@ database:
 app:
   name: '{{name}}'
   environment: development
+
   auth:
-    secret: 'change-me-in-production'
+    secret: '${JWT_SECRET:change-me-in-production}'
     accessTtl: '15m'
+
   i18n:
     default_locale: 'ko'
     fallback: 'en'
+
   docs:
     enabled: true
     path: '/docs'
 
-themes:
-  default: 'default'
+  themes:
+    default: 'default'
+
+# Multi-App (도메인 → 앱 라우팅)
+apps:
+  "localhost": backend
+  # "admin.example.com": backend
+  # "example.com": frontend

package/cli/templates/app/routes/web.js.tpl

@@ -1,5 +1,5 @@
+import HomeController from '../controllers/HomeController.js';
+
 export default (r) => {
-    r.get('/', (ctx) => {
-        ctx.render('home');
-    });
+    r.get('/', HomeController.index);
 };

package/cli/templates/make/middleware.js.tpl

@@ -1,7 +1,7 @@
 import { Middleware } from '@fuzionx/framework';
 
 export default class {{Name}}Middleware extends Middleware {
-    static name = '{{nameLower}}';
+    static alias = '{{nameLower}}';
 
     async handle(ctx, next) {
         // TODO: implement

package/lib/core/Application.js

@@ -77,12 +77,11 @@ export default class Application {
         this._eventHandlers = new Map();
         this._errorHandlers = [];
 
-        // 라우터
-        this._router = new Router();
+        // 멀티앱 레지스트리 (도메인→앱 라우팅)
+        this._appRegistry = new Map();
 
-        // 미들웨어
+        // 글로벌 미들웨어
         this._globalMiddleware = [];
-        this._middlewareRegistry = new Map();
 
         // 프레임워크 컴포넌트
         this.db = new ModelRegistry();
@@ -105,14 +104,15 @@ export default class Application {
         this.storage = null;
         this._scheduler = null;
         this._queue = null;
-        this._view = null;
         this._wsHandlers = new Map();
 
         // DB 연결 매니저
         this._connectionManager = new ConnectionManager();
 
-        // Worker 매니저
-        this._workerPool = new WorkerPool(this);
+        // Worker 매니저 — shared/workers 기준
+        this._workerPool = new WorkerPool(this, {
+            workersDir: path.resolve(this.baseDir, 'shared/workers'),
+        });
 
         /** @type {WorkerPool} public worker 접근 */
         this.worker = this._workerPool;
@@ -148,16 +148,24 @@ export default class Application {
     //  라우터 접근
     // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-    /** 라우터 인스턴스 */
-    get router() { return this._router; }
+    /**
+     * 앱별 라우터 인스턴스
+     * @param {string} [appName] - 앱 이름 (미지정 시 첫 번째 앱)
+     */
+    getRouter(appName) {
+        const name = appName || this._getDefaultAppName();
+        return this._appRegistry.get(name)?.router || null;
+    }
 
     /**
-     * 라우트 파일 로드
+     * 라우트 파일 로드 (특정 앱에)
      * @param {Function} routeCallback - (r: RouteGroup) => void
-     * @see docs/framework/01-routing-controllers.md
+     * @param {string} [appName]
      */
-    routes(routeCallback) {
-        this._router.load(routeCallback);
+    routes(routeCallback, appName) {
+        const name = appName || this._getDefaultAppName();
+        const entry = this._appRegistry.get(name);
+        if (entry?.router) entry.router.load(routeCallback);
     }
 
     // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -178,13 +186,24 @@ export default class Application {
      * @param {string} name - 'auth', 'csrf' 등
      * @returns {Function} - (ctx, next) => void
      */
-    resolveMiddleware(name) {
+    /**
+     * @param {string} name - 미들웨어 이름 (e.g. 'auth', 'role:admin')
+     * @param {string} [appName] - 앱 이름 (앱별 미들웨어 우선 탐색)
+     */
+    resolveMiddleware(name, appName) {
         // 캐시 히트 → zero-allocation (M-1)
-        if (this._mwFnCache?.has(name)) return this._mwFnCache.get(name);
+        const cacheKey = appName ? `${appName}:${name}` : name;
+        if (this._mwFnCache?.has(cacheKey)) return this._mwFnCache.get(cacheKey);
 
         // 파라미터화: 'role:admin' → name='role', params=['admin']
         const [mwName, ...params] = name.split(':');
-        const MwClass = this._middlewareRegistry.get(mwName);
+
+        // 앱별 미들웨어 우선 탐색 → 없으면 무시
+        let MwClass = null;
+        if (appName) {
+            const appEntry = this._appRegistry.get(appName);
+            MwClass = appEntry?.middlewareRegistry?.get(mwName) || null;
+        }
         if (!MwClass) return null;
 
         const instance = new MwClass(this);
@@ -192,7 +211,7 @@ export default class Application {
 
         // 캐시 저장
         if (!this._mwFnCache) this._mwFnCache = new Map();
-        this._mwFnCache.set(name, fn);
+        this._mwFnCache.set(cacheKey, fn);
         return fn;
     }
 
@@ -264,17 +283,10 @@ export default class Application {
 
         await this.emit('booting');
 
-        // 6. i18n 로드 (04-bootstrap-lifecycle.md)
+        // 2. i18n 로드 (04-bootstrap-lifecycle.md)
         await this.i18n.load();
 
-        // View 초기화
-        this._view = new View({
-            viewsPath: path.resolve(this.baseDir, 'views'),
-            theme: this.config.get('themes.default', 'default'),
-            bridge: this._bridge,
-        });
-
-        // Scheduler / Queue / Storage 초기화 (04-bootstrap-lifecycle.md)
+        // 3. Scheduler / Queue / Storage 초기화
         this._scheduler = new Scheduler(this);
         this._queue = new Queue(this, { driver: this.config.get('queue.driver', 'memory') });
         this.storage = new Storage({
@@ -283,16 +295,35 @@ export default class Application {
             fileHelper: this.file,
         });
 
-        // 자동 스캔 (models, services, middleware, events, jobs, ws, routes)
-        const loader = new AutoLoader(this, this.baseDir);
-        await loader.load();
+        // 4. Phase 1: 공유 리소스 로드 (database/models, shared/events,jobs,workers)
+        const sharedLoader = new AutoLoader(this, this.baseDir, { mode: 'shared' });
+        await sharedLoader.load();
+
+        // 5. Phase 2: 앱별 리소스 로드 (app/{name}/controllers,routes,services,middleware,ws,views)
+        const appNames = this._getAppNames();
+        for (const name of appNames) {
+            const appDir = path.resolve(this.baseDir, 'app', name);
+            const appEntry = {
+                name,
+                router: new Router(),
+                controllers: new Map(),
+                controllerCache: new Map(),
+                middlewareRegistry: new Map(),
+                wsHandlers: new Map(),
+                view: new View({
+                    viewsPath: path.resolve(appDir, 'views'),
+                    theme: this.config.get('app.themes.default', 'default'),
+                    bridge: this._bridge,
+                }),
+            };
+            const appLoader = new AutoLoader(this, appDir, { mode: 'app', appContext: appEntry });
+            await appLoader.load();
+            this._appRegistry.set(name, appEntry);
+        }
 
-        // DB 연결 매니저 초기화 (database 섹션이 있을 때만)
+        // 6. DB 연결 매니저 초기화 (database 섹션이 있을 때만)
         const dbConfig = this.config.get('database');
         if (dbConfig) {
-            // connections 키가 없는 레거시 형식 호환:
-            //   database.main: { driver: 'sqlite', ... }
-            //   → database.connections.main: { driver: 'sqlite', ... }
             if (!dbConfig.connections) {
                 const connections = {};
                 for (const [key, val] of Object.entries(dbConfig)) {
@@ -312,20 +343,66 @@ export default class Application {
             }
         }
 
-        // OpenAPI / Swagger UI 라우트 등록 (21-openapi.md)
+        // 7. OpenAPI / Swagger UI 라우트 등록 (모든 앱의 라우트 통합)
         this._registerDocsRoutes();
 
         this._booted = true;
         await this.emit('booted');
     }
 
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  Multi-App 도메인 라우팅
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    /**
+     * config.apps에서 유니크 앱 이름 목록 추출
+     * @returns {string[]}
+     */
+    _getAppNames() {
+        const appsConfig = this.config.get('apps') || {};
+        return [...new Set(Object.values(appsConfig))];
+    }
+
+    /**
+     * 기본 앱 이름 (config.apps의 첫 번째 항목 값)
+     * @returns {string}
+     */
+    _getDefaultAppName() {
+        const appsConfig = this.config.get('apps') || {};
+        const values = Object.values(appsConfig);
+        return values[0] || 'backend';
+    }
+
+    /**
+     * 호스트 → 앱 이름 결정
+     * reverse proxy 경유 시 X-Forwarded-Host 우선 사용.
+     * @param {string} host - 요청 Host 헤더 (port 포함 가능)
+     * @param {object} [headers] - 전체 요청 헤더 (proxy 지원)
+     * @returns {string} 앱 이름
+     */
+    _resolveApp(host, headers) {
+        // reverse proxy: X-Forwarded-Host > X-Original-Host > Host
+        const forwardedHost = headers?.['x-forwarded-host'] || headers?.['X-Forwarded-Host']
+            || headers?.['x-original-host'] || headers?.['X-Original-Host'];
+        const rawHost = forwardedHost || host || '';
+        const hostname = rawHost.split(':')[0]; // 포트 제거
+        const appsConfig = this.config.get('apps') || {};
+
+
+
+        // 정확한 도메인 매칭
+        if (appsConfig[hostname]) return appsConfig[hostname];
+        // 매칭 없으면 첫 번째 앱 (기본)
+        return this._getDefaultAppName();
+    }
+
     /**
      * Bridge 참조를 모든 Helper 인스턴스에 전파
      * @private
      */
     _propagateBridge() {
         if (!this._bridge) return;
-        if (this._view) this._view._bridge = this._bridge;
+        // View는 앱별 → boot()에서 생성 시 bridge 주입됨
         if (this.logger) this.logger._bridge = this._bridge;
         if (this.crypto) this.crypto._bridge = this._bridge;
         if (this.hash) this.hash._bridge = this._bridge;
@@ -426,7 +503,12 @@ export default class Application {
         if (!docsConfig || docsConfig.enabled === false) return;
 
         const docsPath = docsConfig.path || '/docs';
-        const routes = this._router.getRoutes();
+
+        // 모든 앱의 라우트 통합
+        const allRoutes = [];
+        for (const [, appEntry] of this._appRegistry) {
+            allRoutes.push(...appEntry.router.getRoutes());
+        }
 
         // OpenAPI spec 빌드 (1회, 캐싱)
         this._openapi = new OpenAPI({
@@ -435,21 +517,26 @@ export default class Application {
             description: docsConfig.description || '',
             servers: docsConfig.servers || [],
         });
-        this._openapi.build(routes);
+        this._openapi.build(allRoutes);
+
+        // docs 라우트는 기본 앱의 라우터에 등록
+        const defaultAppName = this._getDefaultAppName();
+        const defaultApp = this._appRegistry.get(defaultAppName);
+        if (!defaultApp) return;
 
         // JSON spec
-        this._router.get(`${docsPath}/openapi.json`, (ctx) => {
+        defaultApp.router.get(`${docsPath}/openapi.json`, (ctx) => {
             ctx.json(this._openapi.toJSON());
         });
 
         // YAML spec
-        this._router.get(`${docsPath}/openapi.yaml`, (ctx) => {
+        defaultApp.router.get(`${docsPath}/openapi.yaml`, (ctx) => {
             ctx.setHeader('Content-Type', 'text/yaml; charset=utf-8');
             ctx.send(this._openapi.toYAML());
         });
 
         // Swagger UI HTML (CDN — 외부 의존 없음)
-        this._router.get(docsPath, (ctx) => {
+        defaultApp.router.get(docsPath, (ctx) => {
             const specUrl = `${docsPath}/openapi.json`;
             const title = docsConfig.title || 'API Docs';
             ctx.html(Application._swaggerHtml(title, specUrl));
@@ -492,107 +579,225 @@ export default class Application {
     }
 
     /**
-     * 싱글톤 컨트롤러 초기화
+     * 앱별 싱글톤 컨트롤러 초기화
      * @private
      */
     _initControllers() {
-        this._controllerCache = new Map();
-
-        for (const route of this._router.getRoutes()) {
-            const handler = route.handler;
-            if (handler?.__handler__ && handler.controller) {
-                const CtrlClass = handler.controller;
-                if (!this._controllerCache.has(CtrlClass)) {
-                    this._controllerCache.set(CtrlClass, new CtrlClass(this));
+        for (const [, appEntry] of this._appRegistry) {
+            for (const route of appEntry.router.getRoutes()) {
+                const handler = route.handler;
+                if (handler?.__handler__ && handler.controller) {
+                    const CtrlClass = handler.controller;
+                    if (!appEntry.controllerCache.has(CtrlClass)) {
+                        appEntry.controllerCache.set(CtrlClass, new CtrlClass(this));
+                    }
                 }
             }
         }
     }
 
     /**
-     * 프레임워크 라우트 → Bridge FuzionXApp 라우트 변환
+     * 프레임워크 라우트 → Bridge 라우트 변환 (Host 기반 앱 디스패치)
+     *
+     * 동일 path에 여러 앱이 라우트를 가질 수 있으므로,
+     * 각 method+path 당 하나의 Bridge 핸들러를 등록하고
+     * 런타임에 Host 헤더로 앱을 결정한다.
+     *
      * @private
      */
     _registerBridgeRoutes(coreApp) {
         this._initControllers();
-        const routes = this._router.getRoutes();
 
-        for (const route of routes) {
-            const bridgeHandler = this._createBridgeHandler(route);
-            const method = route.method.toLowerCase();
+        // 디스패치 테이블: "METHOD:path" → Map<appName, { route, middlewareFns }>
+        const dispatch = new Map();
+
+        for (const [appName, appEntry] of this._appRegistry) {
+            for (const route of appEntry.router.getRoutes()) {
+                const key = `${route.method}:${route.path}`;
+                if (!dispatch.has(key)) dispatch.set(key, new Map());
 
-            if (typeof coreApp[method] === 'function') {
-                coreApp[method](route.path, bridgeHandler);
+                // 미들웨어 체인 사전 구성
+                const middlewareFns = [...this._globalMiddleware];
+                if (route.middleware?.length) {
+                    for (const mwName of route.middleware) {
+                        const fn = this.resolveMiddleware(mwName, appName);
+                        if (fn) middlewareFns.push(fn);
+                    }
+                }
+
+                dispatch.get(key).set(appName, { route, middlewareFns });
             }
         }
+
+        // 유니크 path별 하나의 Bridge 핸들러 등록
+        for (const [key, appMap] of dispatch) {
+            const [method, routePath] = [key.split(':')[0].toLowerCase(), key.slice(key.indexOf(':') + 1)];
+            if (typeof coreApp[method] !== 'function') continue;
+
+            const bridgeHandler = this._createDispatchHandler(appMap);
+            coreApp[method](routePath, bridgeHandler);
+        }
     }
 
     /**
-     * WsHandler → Bridge WS 이벤트 연결
+     * WsHandler → Bridge WS 이벤트 연결 (모든 앱의 핸들러)
      * @private
      */
     _registerWsHandlers(coreApp) {
-        if (!this._wsHandlers || this._wsHandlers.size === 0) return;
         if (!coreApp.ws) return;
 
-        for (const [namespace, HandlerClass] of this._wsHandlers) {
-            const eventMap = HandlerClass.buildEventMap();
-            const wsNs = coreApp.ws(namespace);
+        for (const [, appEntry] of this._appRegistry) {
+            if (!appEntry.wsHandlers || appEntry.wsHandlers.size === 0) continue;
+
+            for (const [namespace, HandlerClass] of appEntry.wsHandlers) {
+                const eventMap = HandlerClass.buildEventMap();
+                const wsNs = coreApp.ws(namespace);
+
+                // 싱글톤 인스턴스
+                const inst = new HandlerClass(this);
+
+                wsNs.on('connect', (socket) => {
+                    console.log(`[WS] connect: ${namespace} sid=${socket.sessionId}`);
+                    inst.onConnect(socket);
+                });
+
+                wsNs.on('message', (socket, rawMessage) => {
+                    let parsed;
+                    try { parsed = typeof rawMessage === 'string' ? JSON.parse(rawMessage) : rawMessage; }
+                    catch { parsed = { type: 'message', data: rawMessage }; }
+                    const eventType = parsed.type || 'message';
+                    const eventData = parsed.data || parsed;
+                    console.log(`[WS] msg: ${namespace} type=${eventType} sid=${socket.sessionId}`);
+                    const entry = eventMap.get(eventType);
+                    if (entry) {
+                        const result = entry.handler.call(inst, socket, eventData);
+                        if (result && typeof result.then === 'function') {
+                            result.then(r => { if (r) socket.send(JSON.stringify(r)); })
+                                  .catch(e => console.error(`[WS] error: ${eventType}`, e));
+                        } else if (result) {
+                            socket.send(JSON.stringify(result));
+                        }
+                    } else {
+                        inst.onEvent(socket, eventType, eventData);
+                    }
+                });
 
-            // 싱글톤 인스턴스 — 연결/메시지/해제에서 동일 인스턴스 사용
-            const inst = new HandlerClass(this);
+                wsNs.on('disconnect', (socket) => {
+                    console.log(`[WS] disconnect: ${namespace} sid=${socket.sessionId}`);
+                    inst.onDisconnect(socket);
+                });
 
-            wsNs.on('connect', (socket) => {
-                console.log(`[WS] connect: ${namespace} sid=${socket.sessionId}`);
-                inst.onConnect(socket);
-            });
+                console.log(`[WS] 핸들러 등록: ${namespace} (events: ${[...eventMap.keys()].join(', ')})`);
+            }
+        }
+    }
 
-            wsNs.on('message', (socket, rawMessage) => {
-                let parsed;
-                try { parsed = typeof rawMessage === 'string' ? JSON.parse(rawMessage) : rawMessage; }
-                catch { parsed = { type: 'message', data: rawMessage }; }
-                const eventType = parsed.type || 'message';
-                const eventData = parsed.data || parsed;
-                console.log(`[WS] msg: ${namespace} type=${eventType} sid=${socket.sessionId}`);
-                const entry = eventMap.get(eventType);
-                if (entry) {
-                    const result = entry.handler.call(inst, socket, eventData);
-                    if (result && typeof result.then === 'function') {
-                        result.then(r => { if (r) socket.send(JSON.stringify(r)); })
-                              .catch(e => console.error(`[WS] error: ${eventType}`, e));
-                    } else if (result) {
-                        socket.send(JSON.stringify(result));
+    /**
+     * Host 기반 디스패치 핸들러 생성
+     *
+     * 동일 path에 대해 Host 헤더로 앱을 결정하고
+     * 해당 앱의 route + middleware 체인을 실행.
+     *
+     * @param {Map<string, {route, middlewareFns}>} appMap - appName → {route, middlewareFns}
+     * @returns {Function} Bridge 핸들러
+     * @private
+     */
+    _createDispatchHandler(appMap) {
+        return (req, res) => {
+            // Host 헤더에서 앱 결정 (reverse proxy: X-Forwarded-Host 우선)
+            const host = req.headers?.host || req.headers?.Host || '';
+            const appName = this._resolveApp(host, req.headers);
+
+            // 해당 앱의 route+middleware 찾기 (없으면 기본 앱)
+            let entry = appMap.get(appName);
+            if (!entry) {
+                // 매칭 앱에 이 경로가 없으면 기본 앱 시도
+                const defaultApp = this._getDefaultAppName();
+                entry = appMap.get(defaultApp);
+            }
+            if (!entry) {
+                // 어떤 앱에도 없으면 첫 번째 앱
+                entry = appMap.values().next().value;
+            }
+
+            const { route, middlewareFns } = entry;
+
+            // rawReq → Context
+            const ctx = new Context({
+                method: req.method,
+                url: req.url,
+                path: req.path,
+                query: req.query,
+                params: req.params,
+                headers: req.headers,
+                body: req.body || req.json,
+                remoteIp: req.ip,
+                handlerId: req.handlerId,
+                requestId: req.requestId,
+                sessionId: req.sessionId,
+                session: req.session?._data || {},
+                files: req.files || null,
+                formFields: req.formFields || null,
+            }, this);
+
+            ctx.appName = appName;
+
+            // async 체인 실행 → sendAsyncResponse
+            const promise = this._executeChain(middlewareFns, route, ctx);
+
+            promise.then(() => {
+                const response = ctx.toResponse();
+                const contentType = response.headers?.['Content-Type'] || 'application/json';
+                const headerParts = [];
+                if (response.headers) {
+                    for (const [k, v] of Object.entries(response.headers)) {
+                        if (k !== 'Content-Type') headerParts.push(`${k}: ${v}`);
                     }
-                } else {
-                    inst.onEvent(socket, eventType, eventData);
+                }
+                const extraHeaders = headerParts.length > 0 ? headerParts.join('\r\n') + '\r\n' : '';
+                try {
+                    this._coreApp._bridge.sendAsyncResponse(
+                        req.requestId, response.status,
+                        response.body || '', contentType, extraHeaders,
+                    );
+                } catch (e) {
+                    console.error('[fuzionx] sendAsyncResponse failed:', e.message);
+                }
+            }).catch((err) => {
+                console.error('[fuzionx] Handler error:', err.message || err);
+                try {
+                    this._coreApp._bridge.sendAsyncResponse(
+                        req.requestId, 500,
+                        JSON.stringify({ error: err.message || 'Internal Server Error' }),
+                        'application/json', '',
+                    );
+                } catch (e) {
+                    console.error('[fuzionx] sendAsyncResponse error failed:', e.message);
                 }
             });
 
-            wsNs.on('disconnect', (socket) => {
-                console.log(`[WS] disconnect: ${namespace} sid=${socket.sessionId}`);
-                inst.onDisconnect(socket);
-            });
-
-            console.log(`[WS] 핸들러 등록: ${namespace} (events: ${[...eventMap.keys()].join(', ')})`);
-        }
+            return { async: true };
+        };
     }
 
     /**
-     * 단일 라우트의 Bridge 핸들러 생성
+     * 단일 라우트의 Bridge 핸들러 생성 (앱별)
      * rawReq → Context → middleware → controller → toResponse
+     * @param {object} route
+     * @param {string} appName - 이 라우트가 속한 앱
      * @private
      */
-    _createBridgeHandler(route) {
+    _createBridgeHandler(route, appName) {
         // 미들웨어 체인 사전 구성
         const middlewareFns = [];
 
         // 글로벌 미들웨어
         middlewareFns.push(...this._globalMiddleware);
 
-        // 라우트 미들웨어 (이름 → 인스턴스 변환)
+        // 앱별 라우트 미들웨어 (이름 → 인스턴스 변환)
         if (route.middleware?.length) {
             for (const mwName of route.middleware) {
-                const fn = this.resolveMiddleware(mwName);
+                const fn = this.resolveMiddleware(mwName, appName);
                 if (fn) middlewareFns.push(fn);
             }
         }
@@ -616,6 +821,9 @@ export default class Application {
                 formFields: req.formFields || null,
             }, this);
 
+            // 앱 이름 주입
+            ctx.appName = appName;
+
             // Framework → async 체인 실행 후 직접 sendAsyncResponse
             const promise = this._executeChain(middlewareFns, route, ctx);
 
@@ -698,8 +906,9 @@ export default class Application {
      */
     async _executeHandler(handler, ctx) {
         if (handler?.__handler__) {
-            // 싱글톤 컨트롤러 메서드 참조
-            const instance = this._controllerCache.get(handler.controller);
+            // 앱별 싱글톤 컨트롤러 메서드 참조
+            const appEntry = this._appRegistry.get(ctx.appName);
+            const instance = appEntry?.controllerCache?.get(handler.controller);
             if (instance && typeof instance[handler.method] === 'function') {
                 await instance[handler.method](ctx);
                 return;

package/lib/core/AutoLoader.js

@@ -2,7 +2,9 @@
  * AutoLoader — 앱 디렉토리 자동 스캔 + 등록
  *
  * Application.boot() 시 호출.
- * models/, services/, middleware/ 등 자동 로드.
+ * multi-app 구조:
+ *   mode='shared' → database/models, shared/events, shared/jobs, shared/workers
+ *   mode='app'    → app/{name}/controllers, routes, services, middleware, ws
  *
  * @see docs/framework/04-bootstrap-lifecycle.md
  */
@@ -38,30 +40,39 @@ function extractName(filePath, suffix = '') {
 export default class AutoLoader {
     /**
      * @param {import('./Application.js').default} app
-     * @param {string} baseDir - 프로젝트 루트
+     * @param {string} baseDir - 프로젝트 루트 (shared) 또는 앱 디렉토리 (app)
+     * @param {object} [opts]
+     * @param {'shared'|'app'} [opts.mode='shared']
+     * @param {object} [opts.appContext] - 앱별 레지스트리 (mode='app' 시)
      */
-    constructor(app, baseDir) {
+    constructor(app, baseDir, opts = {}) {
         this.app = app;
         this.baseDir = baseDir;
+        this._mode = opts.mode || 'shared';
+        this._appContext = opts.appContext || null;
     }
 
     /**
-     * 전체 스캔 + 등록 실행
+     * 모드에 따른 스캔 + 등록 실행
      */
     async load() {
-        await this.loadModels();
-        await this.loadControllers();
-        await this.loadServices();
-        await this.loadMiddleware();
-        await this.loadEvents();
-        await this.loadJobs();
-        await this.loadWsHandlers();
-        await this.loadRoutes();
+        if (this._mode === 'shared') {
+            await this.loadModels('database/models');
+            await this.loadEvents('shared/events');
+            await this.loadJobs('shared/jobs');
+            // workers는 WorkerPool._resolve()에서 shared/workers/ 경로로 자동 탐색
+        } else if (this._mode === 'app') {
+            await this.loadControllers();
+            await this.loadRoutes();
+            await this.loadServices();
+            await this.loadMiddleware();
+            await this.loadWsHandlers();
+        }
     }
 
-    /** models/*.js → ModelRegistry */
-    async loadModels() {
-        const files = await scanDir(path.join(this.baseDir, 'models'));
+    /** database/models/*.js → ModelRegistry (공유) */
+    async loadModels(subDir = 'models') {
+        const files = await scanDir(path.join(this.baseDir, subDir));
         for (const file of files) {
             const mod = await import(file);
             const ModelClass = mod.default;
@@ -74,7 +85,7 @@ export default class AutoLoader {
     }
 
     /**
-     * controllers/*.js → 싱글톤 인스턴스 + __handler__ static 등록
+     * controllers/*.js → 앱별 컨트롤러 레지스트리 + __handler__ static 등록
      *
      * 문서 01-routing-controllers.md:
      * 프로토타입 메서드를 static 레퍼런스로 자동 등록하여
@@ -83,9 +94,9 @@ export default class AutoLoader {
     async loadControllers() {
         const controllerDir = path.join(this.baseDir, 'controllers');
         const files = await scanDir(controllerDir);
-        if (!this.app._controllers) {
-            this.app._controllers = new Map();
-        }
+        const registry = this._appContext?.controllers || this.app._controllers;
+        if (!registry) return;
+
         for (const file of files) {
             const mod = await import(file);
             const ControllerClass = mod.default;
@@ -96,7 +107,7 @@ export default class AutoLoader {
 
             // 컨트롤러 이름 등록 (싱글톤 인스턴스는 boot 완료 후 생성)
             const name = extractName(file, 'Controller');
-            this.app._controllers.set(name, ControllerClass);
+            registry.set(name, ControllerClass);
         }
     }
 
@@ -123,7 +134,7 @@ export default class AutoLoader {
         }
     }
 
-    /** services/*.js → DI register */
+    /** services/*.js → DI register (앱별 네임스페이스) */
     async loadServices() {
         const files = await scanDir(path.join(this.baseDir, 'services'));
         for (const file of files) {
@@ -135,24 +146,24 @@ export default class AutoLoader {
         }
     }
 
-    /** middleware/*.js → 이름별 미들웨어 맵 */
+    /** middleware/*.js → 앱별 미들웨어 맵 */
     async loadMiddleware() {
-        if (!this.app._middlewareRegistry) {
-            this.app._middlewareRegistry = new Map();
-        }
+        const registry = this._appContext?.middlewareRegistry || this.app._middlewareRegistry;
+        if (!registry) return;
+
         const files = await scanDir(path.join(this.baseDir, 'middleware'));
         for (const file of files) {
             const mod = await import(file);
             const MwClass = mod.default;
             if (!MwClass) continue;
             const mwName = MwClass.alias || extractName(file, 'Middleware').toLowerCase();
-            this.app._middlewareRegistry.set(mwName, MwClass);
+            registry.set(mwName, MwClass);
         }
     }
 
-    /** events/*.js → EventBus.on() */
-    async loadEvents() {
-        const files = await scanDir(path.join(this.baseDir, 'events'));
+    /** shared/events/*.js → EventBus.on() (공유) */
+    async loadEvents(subDir = 'events') {
+        const files = await scanDir(path.join(this.baseDir, subDir));
         for (const file of files) {
             const mod = await import(file);
             // events/*.js 는 export default (app) => { app.on('...', handler) }
@@ -162,9 +173,9 @@ export default class AutoLoader {
         }
     }
 
-    /** jobs/*.js → Scheduler + Queue */
-    async loadJobs() {
-        const files = await scanDir(path.join(this.baseDir, 'jobs'));
+    /** shared/jobs/*.js → Scheduler + Queue (공유) */
+    async loadJobs(subDir = 'jobs') {
+        const files = await scanDir(path.join(this.baseDir, subDir));
         for (const file of files) {
             const mod = await import(file);
             const JobClass = mod.default;
@@ -182,29 +193,31 @@ export default class AutoLoader {
         }
     }
 
-    /** ws/*.js → WsHandler 등록 */
+    /** ws/*.js → 앱별 WsHandler 등록 */
     async loadWsHandlers() {
-        if (!this.app._wsHandlers) {
-            this.app._wsHandlers = new Map();
-        }
+        const registry = this._appContext?.wsHandlers || this.app._wsHandlers;
+        if (!registry) return;
+
         const files = await scanDir(path.join(this.baseDir, 'ws'));
         for (const file of files) {
             const mod = await import(file);
             const HandlerClass = mod.default;
             if (!HandlerClass) continue;
             const ns = HandlerClass.namespace || '/';
-            this.app._wsHandlers.set(ns, HandlerClass);
+            registry.set(ns, HandlerClass);
         }
     }
 
-    /** routes/*.js → Router.load() */
+    /** routes/*.js → 앱별 Router.load() */
     async loadRoutes() {
+        const router = this._appContext?.router || this.app._router;
+        if (!router) return;
+
         const files = await scanDir(path.join(this.baseDir, 'routes'));
-        if (!this.app._router) return;
         for (const file of files) {
             const mod = await import(file);
             if (typeof mod.default === 'function') {
-                this.app._router.load(mod.default);
+                router.load(mod.default);
             }
         }
     }

package/lib/core/Config.js

@@ -77,10 +77,12 @@ export default class Config {
             if (!line.trim()) continue;
 
             const indent = line.search(/\S/);
-            const match = line.match(/^(\s*)([-\w.]+)\s*:\s*(.*)$/);
+            // 키: unquoted ([-\w.]+) 또는 quoted ("..." / '...')
+            const match = line.match(/^(\s*)(?:(["'])([^"']+)\2|([-\w.]+))\s*:\s*(.*)$/);
             if (!match) continue;
 
-            const [, , key, rawValue] = match;
+            const key = match[3] || match[4]; // quoted key (그룹3) 또는 unquoted key (그룹4)
+            const rawValue = match[5];
 
             // 스택에서 현재 indent보다 깊거나 같은 레벨 제거
             while (stack.length > 1 && stack[stack.length - 1].indent >= indent) {

package/lib/core/Context.js

@@ -318,12 +318,14 @@ export default class Context {
             ...data,
         };
 
-        // Bridge Tera SSR — 폴백 없음
-        if (!this.app?._view) {
-            throw new Error('View not initialized — Bridge not available');
+        // Bridge Tera SSR — 앱별 View 인스턴스 사용
+        const appEntry = this.app?._appRegistry?.get(this.appName);
+        const viewEngine = appEntry?.view;
+        if (!viewEngine) {
+            throw new Error(`View not initialized for app '${this.appName}' — Bridge not available`);
         }
 
-        const html = this.app._view.render(view, globals);
+        const html = viewEngine.render(view, globals);
         return this.html(html);
     }
 

package/lib/http/ErrorHandler.js

@@ -93,7 +93,8 @@ export default class ErrorHandler {
         };
 
         // 테마 에러 페이지 시도 (View 렌더러가 있을 때)
-        const view = this._view || ctx.app?._view;
+        const appEntry = ctx.app?._appRegistry?.get(ctx.appName);
+        const view = this._view || appEntry?.view;
         if (view) {
             const theme = ctx.theme || ctx.app?.config?.get('themes.default', 'default') || 'default';
             // 1. views/{theme}/errors/{code}.html

package/lib/middleware/index.js

@@ -270,15 +270,11 @@ export function session(opts = {}) {
  */
 export function theme(opts = {}) {
     const defaultTheme = opts.default || 'default';
-    const mapping = opts.mapping || {};
 
     return async (ctx, next) => {
-        // YAML 설정에서 매핑 읽기
-        const configMapping = ctx.app?.config?.get('themes.mapping') || mapping;
-        const configDefault = ctx.app?.config?.get('themes.default') || defaultTheme;
-
-        const host = ctx.host?.split(':')[0] || ''; // 포트 제거
-        ctx.theme = configMapping[host] || configDefault;
+        // 앱별 테마 결정 — 도메인→앱 라우팅은 Application._resolveApp()에서 처리
+        const configDefault = ctx.app?.config?.get('app.themes.default') || defaultTheme;
+        ctx.theme = configDefault;
 
         await next();
     };

package/lib/schedule/WorkerPool.js

@@ -212,14 +212,14 @@ export default class WorkerPool {
             return path.resolve(baseDir, name);
         }
 
-        // 3) 단축 이름 → workers/ 폴더 탐색
-        const workersDir = path.resolve(baseDir, 'workers');
+        // 3) 단축 이름 → shared/workers/ 폴더 탐색
+        const workersDir = path.resolve(baseDir, 'shared/workers');
         for (const ext of ['.js', '.mjs']) {
             const candidate = path.join(workersDir, name + ext);
             if (fs.existsSync(candidate)) return candidate;
         }
 
-        // 기본값: workers/{name}.js (존재하지 않아도 Worker 생성 시 에러)
+        // 기본값: shared/workers/{name}.js (존재하지 않아도 Worker 생성 시 에러)
         return path.join(workersDir, name + '.js');
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzionx/framework",
-  "version": "0.1.22",
+  "version": "0.1.24",
   "type": "module",
   "description": "Full-stack MVC framework built on @fuzionx/core — Controller, Service, Model, Middleware, DI, EventBus",
   "main": "index.js",
@@ -34,7 +34,7 @@
     "url": "https://github.com/saytohenry/fuzionx"
   },
   "dependencies": {
-    "@fuzionx/core": "^0.1.22",
+    "@fuzionx/core": "^0.1.24",
     "better-sqlite3": "^12.8.0",
     "knex": "^3.2.5",
     "mongoose": "^9.3.2",