🏢 Boxwood Multi-Tenancy Architecture

flowchart TB subgraph Client["🌐 Client Layer"] REQ["HTTP Request
+ JWT Token"] end subgraph SpringBoot["🍃 Spring Boot Application"] direction TB subgraph Security["Security Layer"] JWT_FILTER["JwtAuthenticationFilter"] TENANT_INT["TenantInterceptor"] end subgraph Context["Context Layer"] TC["TenantContext
(InheritableThreadLocal)"] TRC["TenantReactorContextAccessor
(Reactor Context)"] end subgraph Transaction["Transaction Layer"] MTTM["MultiTenantTransactionManager"] TSTM["TenantSpringTransactionManager"] TTA["TenantTransactionalAspect
(@TenantTransactional)"] end subgraph DataSource["DataSource Layer"] DSC["DataSourceConfig"] TDS["tenantDataSource
(HikariPool: 40)"] SDS["sharedDataSource
(HikariPool: 15)"] end subgraph Tenant["Tenant Management"] TCFG["TenantConfig"] TV["TenantValidator"] TDC["TenantDatabaseCache
(Caffeine)"] DDF["DatabaseDialectFactory"] end end subgraph Database["🗄️ MariaDB"] SHARED["Shared Schema
- tbl_boxwood_tenant
- tbl_user
- 공통 코드"] T1["tenant_A Schema"] T2["tenant_B Schema"] T3["tenant_C Schema"] end REQ --> JWT_FILTER JWT_FILTER --> TENANT_INT TENANT_INT --> TC TC --> TRC TC --> TTA TTA --> MTTM MTTM --> TSTM TSTM --> TDS TSTM --> DDF DSC --> TDS DSC --> SDS TDS --> T1 TDS --> T2 TDS --> T3 SDS --> SHARED TDC --> TDS TV --> TCFG

classDiagram direction TB %% Security Layer class JwtAuthenticationFilter { -JwtTokenService jwtTokenService -TokenStorageService tokenStorageService -AuthenticationService authService +doFilterInternal() -extractAndValidateToken() -setTenantFromToken() } class TenantInterceptor { -DwpAuthService dwpAuthService -BoxwoodTenantRepository tenantRepository -TenantContext tenantContext -TenantConfig tenantConfig -TenantValidator tenantValidator +preHandle() boolean +afterCompletion() -handleWithDwpToken() boolean -handleWithXCompanyHeader() -convertTenantKeyToSchemaName() String } %% Context Layer class TenantContext { -InheritableThreadLocal~String~ currentTenant$ -String defaultSchema +setCurrentTenant(schema)$ TenantContextHolder +getCurrentTenant()$ String +clear()$ +isSet()$ boolean +getCurrentTenantOrDefault() String +executeWithTenant(schema, block) T } class TenantContextHolder { -String previousTenant -boolean closed +close() } class TenantReactorContextAccessor { +TENANT_CONTEXT_KEY$ String +writeToContext()$ Function +getFromContext(contextView)$ String +restoreFromContext(contextView)$ +propagateToMono(mono)$ Mono +syncWithThreadLocal()$ Mono } %% Transaction Layer class TenantSpringTransactionManager { -Database tenantDatabase -DataSource tenantDataSource -TenantValidator tenantValidator -BoxwoodTenantRepository tenantRepository -DatabaseDialectFactory dialectFactory +doGetTransaction() Object +doBegin(transaction, definition) +doCommit(status) +doRollback(status) -switchToSchema(schema) -validateTenantRegistrationAndState(schema) } class TenantTransactionalAspect { -MultiTenantTransactionManager txManager +aroundTenantTransactional() Object +aroundTenantTransactionalClass() Object -handleRegularFunction() Object -handleSuspendFunction() Object } %% DataSource Layer class DataSourceConfig { +tenantDataSource() DataSource +sharedDataSource() DataSource } %% Tenant Management class TenantConfig { +String defaultSchema +String schemaPrefix +String schemaSuffix +int maxTenantCodeLength +boolean allowDefaultFallback +boolean enableDatabaseCache +long databaseCacheMaxSize +long databaseCacheExpireMinutes +boolean validateTenantRegistration +buildSchemaName(tenantCode, profile) String -sanitizeTenantCode(tenantCode) String } class TenantValidator { +validateSchema(schema) String +validateTenantCode(code) String } class TenantDatabaseCache { -DataSource tenantDataSource -TenantValidator tenantValidator -TenantConfig tenantConfig -Cache~String,Database~ cache +getDatabase(schema) Database +invalidate(schema) +invalidateAll() +stats() CacheStats +size() long +isEnabled() boolean } class DatabaseDialectFactory { +detectDialect(dataSource) DatabaseDialect +createDialect(type) DatabaseDialect } class DatabaseDialect { [[interface]] +switchSchema(connection, schema) +getCurrentSchema(connection) String +getDatabaseType() DatabaseType } class MySQLDialect { +switchSchema(connection, schema) +getCurrentSchema(connection) String +getDatabaseType() DatabaseType } %% JWT Service class JwtTokenService { -String jwtSecret -long accessTokenExpiration -long refreshTokenExpiration +generateAccessToken() String +generateRefreshToken() String +extractUsername(token) String +extractUserId(token) Long +extractCompanyId(token) String +isTokenValid(token) boolean +extractDwpClaims(token) DwpClaims } %% Relationships JwtAuthenticationFilter --> JwtTokenService JwtAuthenticationFilter --> TenantContext TenantInterceptor --> TenantContext TenantInterceptor --> TenantConfig TenantInterceptor --> TenantValidator TenantContext --> TenantContextHolder TenantReactorContextAccessor --> TenantContext TenantSpringTransactionManager --> TenantContext TenantSpringTransactionManager --> TenantValidator TenantSpringTransactionManager --> DatabaseDialectFactory TenantTransactionalAspect --> TenantSpringTransactionManager TenantDatabaseCache --> TenantValidator TenantDatabaseCache --> TenantConfig DatabaseDialectFactory --> DatabaseDialect MySQLDialect ..|> DatabaseDialect

sequenceDiagram autonumber participant Client as 🌐 Client participant Filter as JwtAuthenticationFilter participant JwtSvc as JwtTokenService participant Interceptor as TenantInterceptor participant DwpAuth as DwpAuthService participant TenantRepo as BoxwoodTenantRepository participant Context as TenantContext participant Aspect as TenantTransactionalAspect participant TxMgr as TenantSpringTransactionManager participant Validator as TenantValidator participant Dialect as DatabaseDialect participant Pool as TenantDataSource participant DB as MariaDB Client->>Filter: HTTP Request + Authorization Header rect rgb(40, 40, 80) Note over Filter,JwtSvc: 🔐 JWT 인증 단계 Filter->>Filter: extractTokenFromHeader() Filter->>JwtSvc: isTokenValid(token) JwtSvc-->>Filter: true Filter->>JwtSvc: extractCompanyId(token) JwtSvc-->>Filter: "COMPANY_A" end rect rgb(40, 80, 40) Note over Interceptor,Context: 🏢 테넌트 결정 단계 Filter->>Interceptor: preHandle() alt JWT에 companyId 있음 Interceptor->>TenantRepo: findByTenantKey("COMPANY_A") TenantRepo-->>Interceptor: BoxwoodTenant(tenantSchema="boxwood_portal_company_a") else DWP Token 사용 Interceptor->>DwpAuth: verifyDwpToken(cookie) DwpAuth-->>Interceptor: DwpTokenVerifyResponse(companyId) else X-Company Header 사용 Interceptor->>Interceptor: getHeader("X-Company") end Interceptor->>Validator: validateSchema("boxwood_portal_company_a") Validator-->>Interceptor: validated schema Interceptor->>Context: setCurrentTenant("boxwood_portal_company_a") Context-->>Interceptor: TenantContextHolder end rect rgb(80, 40, 40) Note over Aspect,DB: 💾 트랜잭션 & 스키마 전환 단계 Client->>Aspect: @TenantTransactional 메서드 호출 Aspect->>TxMgr: transaction { ... } TxMgr->>Context: getCurrentTenant() Context-->>TxMgr: "boxwood_portal_company_a" TxMgr->>Validator: validateSchema() TxMgr->>TenantRepo: findByTenantSchemaAnyState() TenantRepo-->>TxMgr: BoxwoodTenant(state=ACTIVE) TxMgr->>Pool: getConnection() Pool-->>TxMgr: Connection TxMgr->>Dialect: switchSchema(conn, schema) Dialect->>DB: USE `boxwood_portal_company_a` DB-->>Dialect: OK end rect rgb(60, 60, 80) Note over Client,DB: 📊 비즈니스 로직 실행 Aspect->>DB: SELECT/INSERT/UPDATE... DB-->>Aspect: Result Aspect->>TxMgr: commit TxMgr-->>Aspect: committed end Aspect-->>Client: Response rect rgb(80, 60, 40) Note over Interceptor,Context: 🧹 정리 단계 Interceptor->>Context: clear() Context->>Context: ThreadLocal.remove() end

flowchart TB START([HTTP Request 도착]) --> CHECK_JWT{JWT Token
있음?} CHECK_JWT -->|Yes| PARSE_JWT[JwtTokenService.extractCompanyId] CHECK_JWT -->|No| CHECK_DWP{DWP_TOKEN
Cookie 있음?} PARSE_JWT --> HAS_COMPANY{companyId
추출 성공?} HAS_COMPANY -->|Yes| LOOKUP_DB1[BoxwoodTenantRepository
.findByTenantKey] HAS_COMPANY -->|No| CHECK_DWP CHECK_DWP -->|Yes| VERIFY_DWP[DwpAuthService
.verifyDwpToken] CHECK_DWP -->|No| CHECK_HEADER{X-Company
Header 있음?} VERIFY_DWP --> DWP_VALID{검증 성공?} DWP_VALID -->|Yes| LOOKUP_DB2[BoxwoodTenantRepository
.findByTenantKey] DWP_VALID -->|No| CHECK_HEADER CHECK_HEADER -->|Yes| LOOKUP_DB3[BoxwoodTenantRepository
.findByTenantKey] CHECK_HEADER -->|No| CHECK_FALLBACK{allowDefaultFallback
== true?} LOOKUP_DB1 --> FOUND1{테넌트
찾음?} LOOKUP_DB2 --> FOUND2{테넌트
찾음?} LOOKUP_DB3 --> FOUND3{테넌트
찾음?} FOUND1 -->|Yes| VALIDATE[TenantValidator
.validateSchema] FOUND1 -->|No| BUILD_SCHEMA[TenantConfig
.buildSchemaName] FOUND2 -->|Yes| VALIDATE FOUND2 -->|No| BUILD_SCHEMA FOUND3 -->|Yes| VALIDATE FOUND3 -->|No| BUILD_SCHEMA BUILD_SCHEMA --> VALIDATE VALIDATE --> SET_CONTEXT[TenantContext
.setCurrentTenant] SET_CONTEXT --> SUCCESS([✅ 요청 처리 계속]) CHECK_FALLBACK -->|Yes, Dev/Test| USE_DEFAULT[기본 스키마 사용
defaultSchema] CHECK_FALLBACK -->|No, Production| REJECT([❌ 401 Unauthorized
Tenant identification failed]) USE_DEFAULT --> SET_CONTEXT style START fill:#4a5568 style SUCCESS fill:#48bb78 style REJECT fill:#f56565 style VALIDATE fill:#4299e1 style SET_CONTEXT fill:#9f7aea

sequenceDiagram autonumber participant Service as @TenantTransactional
Service Method participant Aspect as TenantTransactionalAspect participant TxMgr as MultiTenant
TransactionManager participant SpringTx as TenantSpring
TransactionManager participant Validator as TenantValidator participant TenantRepo as BoxwoodTenant
Repository participant Pool as TenantDataSource
(HikariPool) participant DB as MariaDB Service->>Aspect: 메서드 호출 rect rgb(50, 50, 80) Note over Aspect,TxMgr: AOP Advice 실행 Aspect->>Aspect: isSuspendFunction? alt 일반 함수 Aspect->>TxMgr: transaction { joinPoint.proceed() } else suspend 함수 Aspect->>Aspect: runBlocking + withContext Aspect->>TxMgr: transaction { ... } end end rect rgb(80, 50, 50) Note over TxMgr,DB: 트랜잭션 시작 (doBegin) TxMgr->>SpringTx: doBegin() SpringTx->>SpringTx: TenantContext.getCurrentTenant() SpringTx->>Validator: validateSchema(schema) Note over SpringTx,TenantRepo: 테넌트 등록 & 상태 검증 SpringTx->>TenantRepo: findByTenantSchemaAnyState() TenantRepo-->>SpringTx: BoxwoodTenant alt tenant.state == ACTIVE SpringTx->>SpringTx: ✅ 검증 통과 else tenant.state == INACTIVE/SUSPENDED/DELETED SpringTx-->>Aspect: ❌ ETTenantException end Note over SpringTx,DB: 스키마 전환 SpringTx->>Pool: getConnection() Pool-->>SpringTx: Connection SpringTx->>DB: USE `{schema}` DB-->>SpringTx: OK end rect rgb(50, 80, 50) Note over Service,DB: 비즈니스 로직 실행 TxMgr->>Service: proceed() Service->>DB: SQL Queries DB-->>Service: Results end rect rgb(80, 80, 50) Note over TxMgr,DB: 트랜잭션 종료 alt 성공 TxMgr->>SpringTx: doCommit() SpringTx->>DB: COMMIT else 실패 TxMgr->>SpringTx: doRollback() SpringTx->>DB: ROLLBACK end end

sequenceDiagram autonumber participant Admin as 👤 Admin participant API as REST API participant TenantSvc as TenantService participant TenantRepo as BoxwoodTenant
Repository participant SharedDS as SharedDataSource participant TenantDS as TenantDataSource participant Flyway as FlywayMigration
Service participant DB as MariaDB Admin->>API: POST /api/tenants
{tenantKey: "COMPANY_X", ...} API->>TenantSvc: createTenant(request) rect rgb(50, 80, 50) Note over TenantSvc,DB: Step 1: Shared Schema에 법인 정보 등록 TenantSvc->>TenantSvc: TenantConfig.buildSchemaName("COMPANY_X") Note right of TenantSvc: "boxwood_portal_company_x" TenantSvc->>TenantRepo: save(BoxwoodTenant) TenantRepo->>SharedDS: INSERT INTO tbl_boxwood_tenant SharedDS->>DB: [boxwood_portal_*_shared]
INSERT INTO tbl_boxwood_tenant
(tenant_key, tenant_schema, tenant_state, ...) DB-->>SharedDS: OK end rect rgb(80, 50, 50) Note over TenantSvc,DB: Step 2: 테넌트 스키마 생성 TenantSvc->>TenantDS: createSchema() TenantDS->>DB: CREATE SCHEMA IF NOT EXISTS
`boxwood_portal_company_x` DB-->>TenantDS: Schema Created end rect rgb(50, 50, 80) Note over TenantSvc,DB: Step 3: Flyway 마이그레이션 실행 TenantSvc->>Flyway: migrate("boxwood_portal_company_x") Flyway->>TenantDS: USE `boxwood_portal_company_x` loop 각 마이그레이션 파일 Flyway->>DB: V1__init_schema.sql Flyway->>DB: V2__create_tables.sql Flyway->>DB: V3__seed_data.sql Flyway->>DB: ... end Flyway->>DB: INSERT INTO flyway_schema_history DB-->>Flyway: Migration Complete end TenantSvc-->>API: TenantResponse API-->>Admin: 201 Created
{tenantKey, tenantSchema, status}

src/main/resources/
└── db/
    └── migration/
        ├── shared/           # Shared Schema 전용
        │   ├── V1__init_shared.sql
        │   ├── V2__create_tenant_table.sql
        │   └── V3__create_user_table.sql
        └── tenant/           # Tenant Schema 전용
            ├── V1__init_tenant.sql
            ├── V2__create_process_tables.sql
            └── V3__create_workflow_tables.sql
                

flowchart LR subgraph Thread1["Thread #1"] T1_REQ["Request A
tenant: company_a"] T1_CTX["TenantContext
ThreadLocal: company_a"] end subgraph Thread2["Thread #2"] T2_REQ["Request B
tenant: company_b"] T2_CTX["TenantContext
ThreadLocal: company_b"] end subgraph Thread3["Thread #3 (Async)"] T3_CTX["TenantContext
Inherited: company_a"] T3_NOTE["InheritableThreadLocal
부모 Thread에서 상속"] end T1_REQ --> T1_CTX T2_REQ --> T2_CTX T1_CTX -.->|"@Async 호출"| T3_CTX T3_CTX --- T3_NOTE

flowchart TB subgraph Pool["HikariPool (max: 40)"] C1["Connection #1"] C2["Connection #2"] C3["Connection #3"] CN["..."] end subgraph Requests["동시 요청"] R1["Request: tenant_A"] R2["Request: tenant_B"] R3["Request: tenant_A"] end R1 -->|"1. getConnection()"| C1 R1 -->|"2. USE tenant_A"| C1 R1 -->|"3. Query"| C1 R1 -->|"4. Return to pool"| Pool R2 -->|"1. getConnection()"| C2 R2 -->|"2. USE tenant_B"| C2 R3 -->|"1. getConnection()"| C1 R3 -->|"2. USE tenant_A"| C1 style Pool fill:#2d3748 style C1 fill:#48bb78 style C2 fill:#4299e1

flowchart LR subgraph Cache["TenantDatabaseCache (Caffeine)"] direction TB CONFIG["설정
maxSize: 100
expireAfterAccess: 30min"] subgraph Entries["캐시 엔트리"] E1["tenant_a → Database"] E2["tenant_b → Database"] E3["tenant_c → Database"] end end REQ1["getDatabase(tenant_a)"] REQ2["getDatabase(tenant_d)"] REQ1 -->|"Cache HIT"| E1 REQ2 -->|"Cache MISS"| CREATE["createDatabaseForSchema()"] CREATE --> NEW["새 Database 인스턴스"] NEW -->|"캐시 저장"| Cache style Cache fill:#2d3748 style E1 fill:#48bb78 style CREATE fill:#ed8936

flowchart TB subgraph Threats["🔴 위협"] T1["SQL Injection
(스키마명 조작)"] T2["Tenant Isolation 우회
(다른 테넌트 접근)"] T3["미등록 테넌트 접근"] T4["비활성 테넌트 접근"] end subgraph Defenses["🟢 방어"] D1["TenantValidator
- 정규식 검증
- 허용 문자만"] D2["BoxwoodTenantRepository
- DB 등록 확인
- tenantState 검증"] D3["TenantConfig
- allowDefaultFallback=false
(Production)"] D4["TenantSpringTransactionManager
- ACTIVE 상태만 허용"] end T1 --> D1 T2 --> D2 T3 --> D2 T3 --> D3 T4 --> D4 style Threats fill:#742a2a style Defenses fill:#276749