# Residential IP Verifier — User Manual

**Live site:** https://ipverifier.hidenseek.space
**Admin panel:** https://ipverifier.hidenseek.space/admin

---

## 1. What this application does

Residential IP Verifier protects your marketing campaigns from **bad traffic**. You give it
your real "money" page and (optionally) a "safe" page. It gives you back a single **tracking
link**. When you send traffic to that link, the engine inspects every visitor in real time and:

- sends **genuine residential humans** → your real page,
- sends **bots, datacenter IPs, VPNs/proxies, and blocked countries** → your safe page,
- and **logs every visit** so you can see exactly what was allowed or filtered.

There are **two sides** to the app:

| Side | URL | Who | Purpose |
|---|---|---|---|
| **Public website** | `/` | Everyone | Marketing pages, pricing, blog, contact |
| **Customer dashboard** | `/dashboard` | Your customers | Create campaigns, see analytics, manage subscription |
| **Admin panel** | `/admin` | You (owner) | Edit all content, manage users, activate plans, view traffic |

---

## 2. Admin guide (you, the owner)

### 2.1 Logging in
Go to **`/admin`** → email `admin@residentialipverifier.test`, password `password`.
**First task: change this.** Go to **Customers → Users → (the admin user)** and set your own
email + a strong password.

### 2.2 The admin menu (left sidebar), grouped
- **Content** — everything on the public site:
  - *Homepage Sections* — hero, features, stats, call-to-action text & buttons.
  - *Pages (About/Legal)* — the About page (mission, vision, team, stats) and Terms/Privacy.
  - *Services* — the service cards (name, icon, description, image).
  - *Blog Posts* + *Blog Categories* — write articles, set a featured image, schedule them
    (set "Publish at" to a future time and it stays hidden until then).
  - *FAQs* + *FAQ Categories* — questions and answers shown on the FAQ page.
  - *Testimonials* — customer quotes on the homepage.
- **Catalog → Plans** — your pricing plans: price (monthly/quarterly/yearly), feature list,
  limits (how many campaigns / monthly visits), validity. Toggle "featured" to highlight one.
- **Customers**
  - *Users* — all accounts; edit roles, reset access.
  - *Subscription Requests* — when a customer asks for a plan it appears here with a badge.
    Click **Activate** to turn it on (this creates their subscription and emails them).
  - *Subscriptions* — all active/expired subscriptions.
- **Engine**
  - *Campaigns* — every customer's campaign (oversight).
  - *Traffic Logs* — every scored visit: IP, country, verdict (allowed/filtered), reason.
- **Support → Support Tickets / Contact Submissions** — customer messages.
- **Settings** — see below.

### 2.3 Settings (the "no-code" control panel)
- **General** — website name, tagline, description, company name.
- **Branding & Logos** — main/footer/login/email logos + favicon (uploads).
- **Appearance** — primary & secondary colour, button style, font, default light/dark theme.
  *Changes here instantly restyle the whole public site and dashboard.*
- **Contact Information** — address, phone, WhatsApp, email, support email, Google Map embed.
- **SEO & Open Graph** — default meta title/description/keywords and social-share images.
- **Footer** — copyright text, terms/privacy links.
- **Social Links** — Facebook, X, Instagram, LinkedIn, YouTube, Telegram (shown in footer).
- **Email / SMTP** — your outgoing mail server (see §4).
- **IP Intelligence** — choose **Local GeoLite2 files** (default) or the **MaxMind web
  service** (enter account ID + license key for full residential/VPN accuracy).
- **Email Templates** — edit the wording of the 6 automatic emails (welcome, password reset,
  subscription activated/expired, ticket created/reply). Use `{{name}}`, `{{app_name}}` etc.

### 2.4 Media Library
Upload images/PDFs once and reuse them across pages, services and blog posts.

---

## 3. Customer guide (your end users)

### 3.1 Sign up & subscribe
1. Click **Sign Up** → fill name, email, password, accept terms.
2. Go to **Pricing** (or **Dashboard → Subscription**), pick a plan and billing cycle, click
   **Subscribe / Request**.
3. The request goes to the admin. Once the admin **activates** it, the account can route
   traffic. (Billing is handled manually — no card is charged in-app.)

### 3.2 Create a protected campaign
1. **Dashboard → Campaigns → + New Campaign.**
2. Fill in:
   - **Name** — anything memorable.
   - **Allowed (real) URL** — where genuine visitors should go (your offer).
   - **Filtered (safe) URL** — where bad traffic goes (leave blank to use a built-in safe page).
   - **Protection rules** — toggle: block bots, block datacenter IPs, block VPN/proxy,
     residential-only; and optional **allowed/blocked countries** (use 2-letter codes like
     `US, GB`).
3. Save. You'll land on the campaign page showing your **tracking link**
   (e.g. `https://ipverifier.hidenseek.space/c/abc123`). Click **Copy**.

### 3.3 Use the link
Put that tracking link wherever your traffic comes from (ads, posts, redirects). Every click
is scored and routed automatically. **Do not share your real "allowed" URL directly** — always
send traffic through the `/c/...` link so it's protected.

### 3.4 Read your analytics
- **Dashboard (overview)** — total visits, allowed vs filtered, a 14-day chart, top countries,
  and the reasons traffic was filtered.
- **Open a campaign** — per-campaign stats and a live table of recent visits (IP, country,
  verdict, reason).

### 3.5 Support
**Dashboard → Support → New Ticket.** Replies appear in the same thread.

---

## 4. Email setup (important)

Out of the box, emails are written to a log file (not actually sent), so **password-reset and
welcome emails won't arrive** until you configure SMTP:
1. In cPanel → **Email Accounts**, create e.g. `no-reply@hidenseek.space`.
2. In the app: **Admin → Settings → Email/SMTP**, enter the host (`mail.hidenseek.space`),
   port `465`, that email + its password, encryption `SSL`.
3. Save. Test by using "Forgot password" on the login page.

---

## 5. Accuracy of filtering (MaxMind)

The site currently uses **bundled test geo-data**, so country/VPN results are demo-quality.
For production accuracy:
- **Free:** download `GeoLite2-City.mmdb` and `GeoLite2-ASN.mmdb` from your MaxMind account and
  place them in `~/ipverifier_app/storage/app/geoip/` (overwrite the test files).
- **Best:** in **Admin → Settings → IP Intelligence**, switch to the **MaxMind web service** and
  enter your account ID + license key — this gives true residential / VPN / proxy detection.

---

## 6. Quick reference

| I want to… | Go to |
|---|---|
| Change site name / logo / colours | Admin → Settings (General / Branding / Appearance) |
| Add a pricing plan | Admin → Catalog → Plans |
| Activate a customer's plan | Admin → Customers → Subscription Requests → Activate |
| Write a blog post | Admin → Content → Blog Posts |
| See all filtered traffic | Admin → Engine → Traffic Logs |
| Create a protected link | Dashboard → Campaigns → New Campaign |
| See my campaign's results | Dashboard → open the campaign |
| Send real emails | Admin → Settings → Email/SMTP |

---

*Tip: almost everything on the public website is editable from the Admin panel — you should
rarely need to touch code. Log in, explore the left-hand menu, and edit away.*
