# Architecture Decision Record (ADR) - 001: Synology Secure Access

*   **Status**: Accepted
*   **Date**: 2026-01-18
*   **Decision Makers**: Development Team (Gemini & Claude)
*   **Subject**: Secure Remote Access Strategy for Synology Backend services

## Context & Problem
To enable the "Posimai" ecosystem (Sake & Incense apps) to utilize backend services (DB, potentially AI Proxy) hosted on a home Synology NAS, a robust connection strategy is required.
Previous attempts using direct IP (`192.168.x.x`) failed due to lack of external access.
Previous attempts using pure HTTP failed due to Android/iOS security requirements (Cleartext traffic).

## Decision
We will use **Tailscale MagicDNS with HTTPS Certificates** as the primary connectivity solution for the current development phase.

### Justification
1.  **Zero Cost & Zero Hardware**: Tailscale is already running. No new domains or hardware needed.
2.  **Native HTTPS**: Tailscale provides valid Let's Encrypt certificates for `*.ts.net` domains, satisfying Flutter's secure connection requirements.
3.  **Secure by Design**: No open ports (Port Forwarding) required on the router. Access is limited to devices in the Tailnet.
4.  **Sufficiency**: For a user base < 1 person (Developer), the complexity of Cloudflare Tunnel is unnecessary overhead.

### Alternatives Considered
*   **Cloudflare Tunnel**: Best for scaling/production (>10k users), but overkill for now.
*   **QuickConnect**: Synology's proprietary relay. Too slow and hard to integrate with custom ports/containers.
*   **Direct IP / VPN**: Unstable IP addresses and difficult certificates management.

## Implementation Roadmap

### Week 1: Tailscale HTTPS Setup
1.  **MagicDNS**: Enable in Tailscale Admin Console.
2.  **HTTPS Certificates**: Enable in Tailscale Admin Console.
3.  **Result**: `https://posimai-nas.ts.net` becomes a valid, globally accessible (within Tailnet) URL.

### Week 2: Immich & Container Integration
*   Deploy `immich` via Container Manager to act as the media cache.
*   Deploy `posimai-db` (Postgres) for structured data.
*   Configure `docker-compose.yml` (see below).

### Week 3: App Integration
*   Update Flutter App configuration:
    ```dart
    const String apiBaseUrl = 'https://posimai-nas.ts.net';
    ```

## Infrastructure Configuration (`docker-compose.yml`)

```yaml
version: '3.8'
services:
  # Main Database
  posimai-db:
    image: postgres:15-alpine
    container_name: posimai-db
    restart: always
    environment:
      POSTGRES_USER: ${DB_USER}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: posimai_master
    volumes:
      - ./pgdata:/var/lib/postgresql/data
    networks:
      - posimai-net

  # AI Proxy (Legacy/Backup)
  posimai-proxy:
    build: ./ai-proxy
    container_name: posimai-proxy
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      - GEMINI_API_KEY=${GEMINI_API_KEY}
    networks:
      - posimai-net

networks:
  posimai-net:
    driver: bridge
```

## Future Considerations
*   If user base grows > 100, migrate to **Tailscale Funnel** (Public internet access).
*   If user base grows > 10,000, migrate to **Cloudflare Tunnel** + Custom Domain.