2. 아키텍처 (Architecture)¶

2.1 시스템 아키텍처 다이어그램¶

전체 시스템 구조¶

graph TD
    Internet((Internet))
    Nginx[Nginx Proxy<br/>Port 4040]
    Static[Static Files<br/>React SPA]
    API["/api/*<br/>Proxy Pass"]
    Help["/help/*<br/>Static HTML"]
    FastAPI[FastAPI App<br/>Port 9040]
    PG[(PostgreSQL<br/>Shared, 5432)]
    Chroma[(ChromaDB<br/>Vector DB)]
    ExtAPI[External APIs<br/>PubMed, etc.]

    Internet --> Nginx
    Nginx --> Static
    Nginx --> API
    Nginx --> Help
    API --> FastAPI
    FastAPI --> PG
    FastAPI --> Chroma
    FastAPI --> ExtAPI

컨테이너 구성¶

graph TB
    subgraph allergyinsight-network
        FE[frontend<br/>Nginx :4040]
        BE[backend<br/>FastAPI :9040]
        SC[scheduler<br/>APScheduler]
    end

    subgraph database-network [database-network - external]
        PG[(PostgreSQL<br/>shared :5432)]
    end

    FE -->|proxy| BE
    BE --> PG
    SC --> PG

2.2 서비스 구조 (4-App Architecture)¶

프론트엔드 앱 구조¶

┌─────────────────────────────────────────────────────────────────┐
│                         Frontend (React)                         │
├──────────┬──────────┬──────────┬────────────────────────────────┤
│  Admin   │Profession│ Consumer │     Public Apps                │
│ /admin/* │ /pro/*   │ /app/*   │ /analytics/* /ai/* /subscribe  │
├──────────┼──────────┼──────────┼────────────────────────────────┤
│Dashboard │Dashboard │MyDiagnosis│AllergenAnalysis               │
│Users     │Diagnosis │FoodGuide │PaperCollection                │
│Allergens │Patients  │Lifestyle │AllergenNews                   │
│Papers    │Search/QA │Emergency │ComprehensiveTrend             │
│Orgs      │Papers    │KitRegister│AIConsult / AIInsight         │
│News      │Clinical  │          │Subscribe / Report             │
│Subscribers│Report   │          │ClinicalTrials                 │
│Analytics │          │          │                                │
├──────────┴──────────┴──────────┴────────────────────────────────┤
│                      Shared Components                           │
│        (AuthContext, apiClient, Header, Modal, hooks)            │
└─────────────────────────────────────────────────────────────────┘

백엔드 API 구조¶

graph TB
    subgraph "Backend (FastAPI)"
        subgraph "API Layer"
            Admin["/api/admin"]
            Pro["/api/pro"]
            Consumer["/api/consumer"]
            Public["/api/public/analytics<br/>/api/ai/consult<br/>/api/ai/insight<br/>/api/subscribe<br/>/api/report<br/>/api/clinicaltrials"]
        end
        subgraph "Core Modules"
            Auth["Auth<br/>JWT/Google/Email"]
            AllergenDB["Allergen DB"]
            PrescEngine["Prescription Engine"]
            ActivityLog["Activity Logger"]
            RateLimit["Rate Limiter (slowapi)"]
        end
        subgraph "Service Layer (39+ services)"
            PaperSearch["Paper Search"]
            QA["QA Engine / RAG"]
            NewsPipe["News Pipeline"]
            Analytics["Analytics / Trend"]
            SubEmail["Subscription / Email"]
            Scheduler["Scheduler"]
        end
        subgraph "Data Layer"
            SQLAlchemy["SQLAlchemy 2.0<br/>asyncpg + psycopg2"]
            ChromaDB["ChromaDB (Vector)"]
        end
    end

    Admin --> Auth
    Pro --> Auth
    Consumer --> Auth
    Auth --> PrescEngine
    PrescEngine --> SQLAlchemy
    PaperSearch --> SQLAlchemy
    QA --> ChromaDB

라우팅 구조¶

2.3 데이터 흐름도 (Data Flow)¶

진단 → 처방 → 임상 보고서 흐름¶

sequenceDiagram
    participant 의료진
    participant Frontend
    participant Backend
    participant Database

    의료진->>Frontend: 1. 진단 입력
    Frontend->>Backend: 2. POST /api/pro/diagnosis
    Backend->>Backend: 3. 처방 엔진 + GRADE 평가
    Backend->>Database: 4. 저장
    Backend->>Frontend: 5. 처방 권고 + 임상 보고서
    Frontend->>의료진: 6. 결과 표시

뉴스 파이프라인 흐름¶

sequenceDiagram
    participant Scheduler as Scheduler (APScheduler)
    participant News as News Service
    participant DB as Database

    Scheduler->>News: 1. CRON 트리거
    News->>News: 2. Google/Naver News 크롤링
    News->>News: 3. Gemini/LLM 관련도 분석
    News->>DB: 4. 뉴스 저장
    News->>News: 5. 뉴스레터 생성
    News-->>DB: 6. Email 발송 기록

RAG 기반 AI 상담 흐름¶

sequenceDiagram
    participant 사용자
    participant Frontend
    participant Backend
    participant ChromaDB

    사용자->>Frontend: 1. 질문 입력
    Frontend->>Backend: 2. POST /api/ai/consult/ask
    Backend->>ChromaDB: 3. 벡터 검색
    ChromaDB->>Backend: 4. 관련 논문
    Backend->>Backend: 5. Gemini 답변 생성
    Backend->>Frontend: 6. 답변 + 출처
    Frontend->>사용자: 7. 결과 표시

2.4 기술 스택 (Tech Stack)¶

2.5 LLM 이중 아키텍처¶

구성¶

graph LR
    subgraph "Gemini API (Cloud, High Quality)"
        G1["뉴스 분석<br/>관련도 평가"]
        G2["RAG 답변 생성"]
        G3["AI 상담 답변"]
        G4["인사이트 생성"]
    end

    subgraph "Local LLM (Self-hosted, Fast)"
        L1["한→영 번역"]
        L2["알러젠 코드 추출"]
        L3["텍스트 정규화"]
    end

    App[AllergyInsight Backend] --> G1
    App --> G2
    App --> G3
    App --> G4
    App --> L1
    App --> L2
    App --> L3

환경 변수¶

2.6 인프라 구성¶

운영 환경¶

graph TB
    subgraph "Production Server (MacBook Docker) 172.30.1.72"
        FE[Frontend :4040]
        BE[Backend :9040]
        SC[Scheduler<br/>background]

        subgraph "database-network (외부 공유)"
            PG[(PostgreSQL<br/>shared)]
        end

        FE --> BE
        BE --> PG
        SC --> PG
    end

    VOL[/"Volumes:<br/>backend_downloads<br/>chromadb_data"/]
    BE --- VOL

네트워크 구성¶

2.7 보안 아키텍처¶

인증 방식¶

인가 (Authorization)¶

역할	Professional	Consumer	Admin	Public APIs
비인증
patient
doctor
nurse
lab_tech	(제한적)
hospital_admin			(병원)
admin
super_admin

보안 기능¶

2.8 확장성 고려사항¶

현재 (Modular Monolith)¶

graph TB
    subgraph "AllergyInsight"
        Pro[Pro]
        Consumer[Consumer]
        Admin[Admin]
        Analytics[Analytics]
        AI[AI Portal]
        Newsletter[Newsletter]

        Core["Shared Core + Services"]

        Pro --> Core
        Consumer --> Core
        Admin --> Core
        Analytics --> Core
        AI --> Core
        Newsletter --> Core
    end

    Core --> PG[(PostgreSQL)]
    Core --> Chroma[(ChromaDB)]

Scheduler 분리 패턴¶

← 프로젝트 개요 | 다음: 도메인 모델 →