Domain_web/premium/docs/ARCHITECTURE.md

Architecture

GeoExport is a full-stack web application for browsing geoip/geosite rule catalogs, exporting plain-text lists, and generating client routing snippets. This document describes the target architecture for geoexport-premium and how it relates to the existing static mirror.

Goals

1. Self-hosted — operators run their own instance; no mandatory third-party backend.
2. API-first — every UI action has a REST equivalent for scripts and panels.
3. Fast catalog UX — presets and sources are served from cache/DB, not parsed on each page view.
4. Heavy work off the hot path — .dat ingestion and DNS resolution run in workers or upstream services.

System context

flowchart LR
  subgraph clients [Clients]
    Browser[Web UI]
    CLI[Scripts / panels]
  end

  subgraph geoexport [GeoExport]
    Next[Next.js App Router]
    API[REST /api]
    Worker[Geo workers]
  end

  subgraph data [Data plane]
    PG[(PostgreSQL)]
    RD[(Redis)]
    GH[GitHub rule releases]
  end

  Browser --> Next
  CLI --> API
  Next --> API
  API --> PG
  API --> RD
  Worker --> PG
  Worker --> GH
  API --> Worker

Layers

Presentation (src/app, src/components)

• Next.js App Router — server components for catalog pages; client components for search, export, DNS lookup, routing builder.
• Tailwind CSS 4 + shadcn/ui — design system aligned with Linear/Vercel density.
• Framer Motion — transitions for panels, modals, and theme toggle.

API (src/app/api — planned)

Route handlers mirror the public contract documented in API.md:

Concern	Implementation
Catalog	Read presets/sources from PostgreSQL or baked JSON during bootstrap
Search	Redis-backed index or PostgreSQL full-text
Export	Stream plain text from resolved category lists
Lookup	DNS resolver + geodb membership check
Routing	Template engine for Xray / Mihomo / Sing-box snippets

During migration, some routes may proxy to GEOEXPORT_UPSTREAM (default https://geoexport.org), matching behavior in Domain_web server.mjs.

Data (prisma/ — planned)

Model area	Purpose
Source	Rule repo metadata (slug, URLs, compatibility)
PresetGroup / Service	Curated UI presets
Category	geoip:/geosite: entries per source
RoutingPreset	Saved routing templates
UpdateJob	Refresh status for .dat pulls

Cache (redis)

• Catalog responses (presets, sources, last-update)
• Search result pages
• Rate limiting counters for public API

Workers (planned)

Background jobs:

1. Download geoip.dat / geosite.dat from configured GitHub releases.
2. Parse and upsert category index into PostgreSQL.
3. Expose progress via GET /api/update/status.

Deployment topologies

A — Single VPS (Docker Compose)

web + postgres + redis on one host. nginx terminates TLS and proxies to port 3000.

B — Split managed

• Next.js on Vercel / Cloudflare Pages
• Neon / RDS for PostgreSQL
• Upstash for Redis

C — Mirror-only (legacy)

Domain_web: static SPA + Node proxy on port 4173. No PostgreSQL. Suitable until the Next.js port is feature-complete.

Repository layout (target)

geoexport-premium/
├── src/
│   ├── app/                 # routes, layouts, API handlers
│   ├── components/          # UI primitives (shadcn)
│   └── lib/                 # db, redis, geo parsers
├── prisma/
│   └── schema.prisma
├── public/
├── docs/
├── docker-compose.yml
├── Dockerfile
└── .env.example

Compatibility matrix

Client	Import format	Notes
Xray	geoip.dat, geosite.dat, routing rules	Primary target
3x-ui	Same as Xray	Panel import
V2Ray	.dat lists	v2fly source
Mihomo	YAML routing	Generator output
Sing-box	JSON / rule-set	Generator output

Security boundaries

• Public read APIs are unauthenticated by default; operators should place GeoExport behind VPN or enable API keys (roadmap).
• DNS lookup must be rate-limited to prevent abuse as an open resolver.
• Upstream proxy mode forwards only whitelisted /api/* paths — never arbitrary SSRF targets.

Evolution from Domain_web

Domain_web	geoexport-premium
Static index.html + server.mjs	Next.js SSR/ISR
JSON files in data/	PostgreSQL + optional JSON seed
Proxied dynamic API	Native handlers + workers
systemd + nginx install script	Docker Compose + generic reverse proxy