mirror of
https://github.com/andrey271192/Domain_web.git
synced 2026-09-21 14:51:57 +00:00
93109106bc
Bundle geoexport-premium (Docker, docs, Next.js) alongside the working static site mirror; production VPS install still uses site/. Co-authored-by: Cursor <cursoragent@cursor.com>
146 lines
4.7 KiB
Markdown
146 lines
4.7 KiB
Markdown
# 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
|
|
|
|
```mermaid
|
|
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](./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](https://github.com/andrey271192/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](https://github.com/andrey271192/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 |
|