ponshu-room-lite/docs/archive/ARCHITECTURE_DECISION_RECORD_bk.md

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:

  const String apiBaseUrl = 'https://posimai-nas.ts.net';
  

Infrastructure Configuration (docker-compose.yml)

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.