mirror of
https://github.com/andrey271192/Domain_web.git
synced 2026-09-21 14:51:57 +00:00
feat: add premium Next.js scaffold to Domain_web
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>
This commit is contained in:
Андрей Бобырев
145
premium/docs/ARCHITECTURE.md
Normal file
145
premium/docs/ARCHITECTURE.md
Normal file
@@ -0,0 +1,145 @@
|
||||
# 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 |
|
||||
Reference in New Issue
Block a user