3.1 KiB

Raw Blame History

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

Zero Cost & Zero Hardware: Tailscale is already running. No new domains or hardware needed.
Native HTTPS: Tailscale provides valid Let's Encrypt certificates for *.ts.net domains, satisfying Flutter's secure connection requirements.
Secure by Design: No open ports (Port Forwarding) required on the router. Access is limited to devices in the Tailnet.
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

MagicDNS: Enable in Tailscale Admin Console.
HTTPS Certificates: Enable in Tailscale Admin Console.
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.

3.1 KiB Raw Blame History