# Technical Specification - GreetingApp

## Revision History
| Version | Date | Description | Author |
|---|---|---|---|
| v1.0 | 2026-06-22 | Technical specification for GreetingApp | Antigravity Orchestrator |

---

## 1. System Architecture
The GreetingApp consists of three major components:
1. **Greeting Engine (Core):** Performs validation, detects time-of-day categories, maps to localization files, and builds the string.
2. **Storage Layer:** A lightweight JSON/SQLite file logger to record history.
3. **Interfaces:**
   - CLI Controller: Handles flags and standard output formatting.
   - REST Controller: Express.js routes and JSON responses.

## 2. Detailed Component Specs

### 2.1 Greeting Engine (`core/GreetingEngine`)
- **Input:**
  - `name`: string (optional, default: "Guest")
  - `lang`: string (optional, default: "en")
  - `timezone`: string (optional, default: system timezone)
- **Time Periods:**
  - `Morning`: 05:00 - 11:59
  - `Afternoon`: 12:00 - 17:59
  - `Evening`: 18:00 - 21:59
  - `Night`: 22:00 - 04:59
- **Localization Files (`locales/*.json`):**
  - Example `en.json`:
    ```json
    {
      "morning": "Good morning, {name}!",
      "afternoon": "Good afternoon, {name}!",
      "evening": "Good evening, {name}!",
      "night": "Good night, {name}!"
    }
    ```

### 2.2 Storage Schema
A SQLite or JSON lines file containing:
- `id`: UUID / Auto-increment integer
- `name`: String
- `language`: String
- `timestamp`: ISO-8601 string
- `greeting_message`: String

## 3. Interface Design

### 3.1 CLI Interface
`awkit greet [options]`
- `--name, -n`: Name of the user to greet.
- `--lang, -l`: Language code (en, vi, ja).
- `--help, -h`: Show usage description.

### 3.2 REST API Specification
`GET /api/greet`
- **Query Parameters:**
  - `name` (string)
  - `lang` (string)
- **Response (200 OK):**
  - Content-Type: `application/json`
  - Body:
    ```json
    {
      "status": "success",
      "data": {
        "message": "Good morning, Alice!",
        "name": "Alice",
        "lang": "en",
        "timestamp": "2026-06-22T05:35:15Z"
      }
    }
    ```

## 4. Error Handling
- **Invalid Language:** Fallback to `en` and log warning.
- **Invalid Input characters:** Sanitize inputs to prevent command line injection or XSS (on API side).

## 5. Flow Diagram
```mermaid
graph TD
    A[Start Request] --> B{Validate Inputs}
    B -- Invalid --> C[Use Defaults: Guest/en]
    B -- Valid --> D[Resolve User Local Time]
    C --> D
    D --> E{Determine Time of Day}
    E -->|05:00-11:59| F[Morning Template]
    E -->|12:00-17:59| G[Afternoon Template]
    E -->|18:00-21:59| H[Evening Template]
    E -->|22:00-04:59| I[Night Template]
    F & G & H & I --> J[Replace {name} in Template]
    J --> K[Log Transaction to History DB]
    K --> L[Format Output CLI/REST]
    L --> M[End Request]
```