# QA Healthcare Architecture

## Overview

QA Healthcare (医疗问答系统) is an online medical consultation platform connecting patients with doctors for remote Q&A consultations. The system consists of two projects:

- **qa-live-healthcare** - Frontend-only prototype with in-memory mock data (no backend)
- **qa-healthcare** - Production project with Spring Boot microservices backend + Vue.js frontend (currently disconnected)

## System Architecture

```
┌─────────────────────────────────────────────────────────┐
│                    Frontend (Vue 3 SPA)                  │
│              Ant Design Vue + Reactive Store             │
│                    Port 5173 (Vite Dev)                  │
└──────────────────────┬──────────────────────────────────┘
                       │ (NOT YET CONNECTED)
                       │
┌──────────────────────┼──────────────────────────────────┐
│             Backend Microservices (Spring Boot)          │
│                                                         │
│  ┌───────────────┐ ┌────────────────┐ ┌──────────────┐ │
│  │  User Service │ │Question Service│ │ Statistic Svc │ │
│  │   Port 8080   │ │   Port 8081    │ │   (planned)   │ │
│  └───────────────┘ └────────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────┘
```

## Frontend Architecture

### Technology Stack

| Layer | Technology |
|-------|-----------|
| Framework | Vue 3.5.10 (Composition API, `<script setup>` SFCs) |
| UI Library | Ant Design Vue 4.2.6 |
| State Management | Vue 3 `reactive()` (no Pinia/Vuex) |
| Router | Vue Router 4 (createWebHistory) |
| Date Handling | Day.js |
| Build | Vite 5.4.8 |
| Testing | Vitest 4.1.10 + happy-dom + @vue/test-utils (qa-healthcare only) |
| Language | TypeScript |

### Component Structure

```
src/
├── main.ts                  # App entry: createApp + Ant Design + Router
├── App.vue                  # Root layout: AppHeader + RouterView + AppFooter
├── style.css                # Global CSS
├── assets/                  # Static assets
├── components/
│   ├── AppHeader.vue        # Navigation bar + Doctor Login button
│   ├── AppFooter.vue        # Footer
│   └── HelloWorld.vue       # Unused starter leftover
├── data/                    # Static mock data (JSON)
│   ├── doctor-user-list.json  # 5 seed doctors
│   ├── patient-user.json      # 5 seed patients
│   └── question-list.json     # 7 seed questions
├── router/
│   └── index.ts             # 7 routes
├── store/
│   └── index.ts             # Reactive global state store
└── views/
    ├── Home.vue             # Landing page: hero + statistics + doctor rooms
    ├── Consultation.vue     # Patient portal: verify -> submit question -> view answers
    ├── DoctorLogin.vue      # Doctor login form
    ├── DoctorRoom.vue       # Doctor dashboard: pending/answered questions
    ├── Doctors.vue          # Doctor directory with online/offline status
    └── About.vue            # Static info page
```

### Routes

| Path | View | Description |
|------|------|-------------|
| `/` | Home | Landing page |
| `/consultation` | Consultation | Patient consultation portal |
| `/consultation/:doctorUsername` | Consultation | Direct doctor consultation |
| `/doctors` | Doctors | Doctor directory |
| `/doctor/login` | DoctorLogin | Doctor authentication |
| `/doctor/room/:username` | DoctorRoom | Doctor dashboard |
| `/about` | About | Project information |

### Data Flow (Current - Prototype Mode)

All data flows in-memory with no backend communication:

```
Static JSON files → Reactive Vue Store (store/index.ts) → Vue Components → UI
```

### User Flows

**Patient Flow:**
1. `/consultation` -> Enter name + birthday for identity verification (`store.verifyPatient()`)
2. Auto-match or create patient record
3. Select a doctor -> Submit question (`store.addQuestion()`)
4. View answered questions with doctor replies

**Doctor Flow:**
1. `/doctor/login` -> Enter credentials (`store.loginDoctor()`)
2. Redirect to `/doctor/room/:username` -> Dashboard
3. View pending questions (`store.getQuestionsByDoctor()`)
4. Submit answer (`store.answerQuestion()`) or mark verbally answered (`store.markQuestionAsAnswered()`)
5. Share consultation room URL with patient

## Backend Architecture

### Technology Stack

| Layer | Technology |
|-------|-----------|
| Framework | Spring Boot 3.5.7 |
| Language | Java 17 (POM) / Java 21 (runtime) |
| Build | Maven (mvnw wrapper) |
| Group ID | com.leansofx |
| Monitoring | Spring Boot Actuator (user service only) |

### Microservices

#### qa-service-user (Port 8080)

- **Status:** Early development
- **Dependencies:** spring-boot-starter-web, spring-boot-starter-actuator
- **Implemented:** `CorsConfig.java`, `TestController.java` (CORS test endpoint only)
- **Actuator Endpoints:** health, info, metrics, env, beans, loggers
- **Package Structure (Planned):**
  ```
  com.leansofx.qaserviceuser/
  ├── config/          # Configuration classes (CorsConfig)
  ├── controller/      # REST controllers
  ├── service/         # Business logic
  ├── repository/      # Data access (planned: JPA)
  ├── entity/          # Domain entities
  └── dto/             # Data transfer objects
  ```

#### qa-service-question (Port 8081)

- **Status:** Skeletal - startup class only, no business logic
- **Dependencies:** spring-boot-starter-web, spring-boot-testcontainers
- **Implemented:** `QaServiceQuestionApplication.java` only

#### qa-service-statistic

- **Status:** Not started (empty directory with `.gitkeep`)

### Backend Service Communication

Currently no inter-service communication. Planned architecture includes:
- API Gateway (Kong/NGINX/Spring Cloud Gateway)
- Auth Service (Spring Security/Keycloak)
- JWT authentication
- Message queues between services

## Development Workflow

### Startup Commands

```bash
# Frontend only (prototype)
cd qa-live-healthcare && npm run dev

# Full stack (production project)
cd qa-healthcare && npm run dev   # concurrently runs all services

# Individual backend services
cd qa-healthcare/server/qa-service-user && ./mvnw spring-boot:run
cd qa-healthcare/server/qa-service-question && ./mvnw spring-boot:run

# Frontend only (production project)
cd qa-healthcare/web/qa-web && npm run dev

# Tests
cd qa-healthcare/web/qa-web && npm run test        # Vitest
cd qa-healthcare/web/qa-web && npm run test:coverage # Vitest + coverage
```

### Orchestration

Root `package.json` in `qa-healthcare` uses `concurrently` to launch frontend + all backend services together.

## Known Issues

1. **Frontend-backend disconnected** - No API calls, HTTP client, or Vite proxy configuration
2. **CORS conflict** - `application.properties` sets `allow-credentials=false`, but `CorsConfig.java` sets `allow-credentials=true`
3. **qa-service-question has no business logic** - Only a startup class
4. **qa-service-statistic is empty** - Just `.gitkeep`
5. **No Vite API proxy** - `vite.config.ts` has no proxy for backend services
6. **No database** - No JPA/database dependencies in any backend service
7. **No CI/CD** - No Jenkinsfile, Dockerfile, or GitHub Actions
8. **Security concerns** - Plain-text passwords in mock data; patient verification uses name + birthday only
9. **ASDM specs are generic templates** - Architecture/API/data-model specs contain e-commerce examples, not healthcare domain content

## Planned Architecture (Not Yet Implemented)

```
┌────────────┐
│ API Gateway│  (Kong / Spring Cloud Gateway)
└──────┬─────┘
       │
┌──────┼──────────────────────────────────────┐
│      │         Service Mesh                  │
│  ┌───┴───┐  ┌────────────┐  ┌────────────┐ │
│  │ Auth  │  │User Service│  │Question Svc│ │
│  │(JWT)  │  │  Port 8080 │  │  Port 8081 │ │
│  └───────┘  └────────────┘  └────────────┘ │
│                    ┌────────────┐            │
│                    │Statistic Svc│            │
│                    └────────────┘            │
│                                             │
│  ┌──────────────┐  ┌──────────────────────┐ │
│  │Message Queue │  │Cache (Redis/Elastic) │ │
│  └──────────────┘  └──────────────────────┘ │
│                                             │
│  ┌─────────────────────────────────────────┐│
│  │  PostgreSQL + Elasticsearch             ││
│  └─────────────────────────────────────────┘│
└─────────────────────────────────────────────┘
```