# 아키텍처

## 핵심 경계

qpost는 하나의 Laravel 애플리케이션에서 두 데이터 영역을 운영한다.

- **Central/Platform**: `App\Models\Platform`, `App\Http\Controllers\Platform`, 중앙 DB. 사용자·Tenant·도메인·플랫폼 관리·AI 정책/가격·Credit·Tagmoa 수집 데이터를 담당한다.
- **Tenant**: `App\Models\Tenant`, `App\Http\Controllers\Tenant`, tenant DB. 사이트 설정, 회원, 팀, 게시판, 글, 댓글, 태그, 게시글 이미지를 담당한다.
- `App\Models\Tenant` 모델은 tenant 초기화 뒤 tenant 연결을 사용하며, Central 모델과 데이터를 혼용하지 않는다.

주요 공통 도메인 코드는 `app/Core` 아래에 있다. 서비스는 `app/Services/Platform`, `app/Services/Tenant` 및 공용 서비스로 나뉜다.

## tenancy와 요청 흐름

Central 도메인의 `routes/web.php`가 `/sites/{tenant}` 요청을 받는다. 이 그룹은 `InitializeTenancyByPath`, `tenant.existing`, `tenant.session.reset`, `tenant.canonical` middleware를 거친 뒤 `routes/tenant-app.php`를 로드한다. 따라서 path tenant는 `/sites/{tenant}`에서 tenant를 초기화한다.

Tenant의 subdomain/custom-domain 라우팅은 `bootstrap`/tenancy 설정과 도메인 정책 middleware의 실제 동작을 함께 확인해야 한다. URL은 현재 접근 방식 보존을 위해 `tenant_url`, `tenant_admin_url`, `tenant_login_url`을 사용한다.

## 라우팅 책임

- Central 공개/플랫폼 관리: `routes/web.php`
- Tenant 공개/회원/관리자: `routes/tenant-app.php`
- 외부 연동 API: `routes/api.php`
- Tenant 게시판 URL은 `/{board}` 그룹 아래에 있고, path tenant에서는 상위 `/sites/{tenant}` prefix가 붙는다.
- wildcard board route보다 `/sites/{tenant}`와 플랫폼 고정 route가 먼저 선언되어야 한다.

## 데이터베이스

Central migration은 `database/migrations`, tenant migration은 `database/migrations/tenant`에 둔다. Tenant provisioning은 `TenantProvisioningService`가 담당하며 기본 구현은 tenant별 SQLite 파일을 사용한다. Central에는 tenants/domains와 Platform 모델의 테이블이 있고, tenant DB에는 site_settings, users, boards, posts, tags, comments, post_images 등이 있다.

## 요청 계층

라우트 → middleware/권한 → controller → Core query/service 또는 도메인 service → model/DB → Blade/JSON 순서다. 인증은 `web`과 `tenant` guard가 분리되어 있고, tenant 관리자 권한은 `tenant.role:*`, 플랫폼 관리자는 `platform.admin`이 검사한다.

## Frontend/backend 경계

Blade가 초기 HTML과 설정 데이터를 렌더링하고, Vite의 `resources/js/app.js`가 공통 JS와 필요한 동적 모듈을 초기화한다. Tenant 화면은 `resources/views/tenant/layouts/base.blade.php`에서 `app.css`, 테마 CSS, `app.js`, `tenant.js`를 로드한다.

## 테스트

`tests/Feature`는 HTTP·권한·라우팅·페이지 흐름, `tests/Unit`은 Core/service/정책/계산 로직을 검증한다. Tenant 관련 테스트는 tenant 초기화와 DB 격리를 전제로 한다.

## 주요 패키지

현재 `composer.json` 기준 주요 의존성은 Laravel Framework `^12.0`, `stancl/tenancy ^3.10`, `spatie/laravel-sitemap ^8.0`, Vite/Laravel Vite plugin, Tailwind CSS Vite plugin이다. 정확한 설치 버전은 lock 파일을 기준으로 확인한다.