# START HERE
## Lesson-Based Onboarding for code::core DNS Analytics

This document is your entry lesson.
Use it to move from zero context to a working DNS analytics stack with clear checkpoints.

---

## Lesson 0: Orientation
Objective: understand what each file teaches before touching infrastructure.

Interpret:
- This lesson teaches document-to-purpose mapping before technical execution.
- You verify where to learn architecture, analytics, and deployment before running commands.

Run:
1. Open index.html for the full interactive teaching manual.
2. Read README.md for architecture and operations lessons.
3. Read SQL_QUERIES.md for guided analytics labs.
4. Read CLOUDFLARE_DEPLOYMENT.md for publishing and edge lessons.

Checkpoint:
- You can explain the four pipeline layers: resolver, ingest, aggregation, decision.

---

## Lesson 1: Build the Local Lab
Objective: install and run the platform on Ubuntu 24.04.

Interpret:
- This lesson teaches one-time bootstrap installation as the platform foundation.
- You verify installation outcomes through focused checks instead of repeated reinstall cycles.

Run:
```bash
sudo bash install.sh
```

Checkpoint:
- Script completes without fatal errors.
- Services are running after installation.

---

## Lesson 2: Verify the Data Path
Objective: prove each stage is producing output.

Interpret:
- This lesson teaches pipeline validation in true data-flow order.
- You verify exactly which layer fails by checking query generation, ingestion, and persistence separately.

Run:
```bash
dig @127.0.0.1 google.com A
sudo journalctl -u dns-ingestor -n 30
psql -U dns_user -d dns_analytics -h localhost -c "SELECT COUNT(*) FROM dns_queries;"
```

Checkpoint:
- DNS answers are returned.
- Ingestor logs show flush/write events.
- dns_queries count increases over time.

---

## Lesson 3: MikroTik Home Lab Mode
Objective: operate with local domain and local zone analytics.

Interpret:
- This lesson teaches hybrid DNS behavior across local zone resolution and recursive internet lookups.
- You verify that both naming correctness and analytics visibility are working in the same pipeline.

Lab assumptions:
- Network: 10.10.10.0/24
- Router and DNS: 10.10.10.10
- Local domain: codeandcore.home

Run:
1. Apply MikroTik DHCP domain and DNS settings from Chapter 7 in index.html.
2. Create BIND authoritative zone codeandcore.home.
3. Seed dns_zone_records table in PostgreSQL.
4. Execute Lesson 9 in SQL_QUERIES.md.

Checkpoint:
- Local names resolve, for example nas.codeandcore.home.
- Local-zone queries appear in analytics.
- Zone inventory and query usage are both visible in SQL.

---

## Lesson 4: First Analytics Readout
Objective: produce a meaningful report from collected traffic.

Interpret:
- This lesson teaches conversion of telemetry into operational insight.
- You verify that reports explain behavior patterns, not just return result sets.

Run:
1. Open SQL_QUERIES.md.
2. Complete Lesson 1 (Traffic Baseline).
3. Complete Lesson 2 (Peak Hours).
4. Complete Lesson 3 (Failure Analysis).

Checkpoint:
- You can answer: top domains, peak hours, and top failure sources.

---

## Lesson 5: Publish and Secure (Optional)
Objective: expose teaching content and controlled analytics endpoints.

Interpret:
- This lesson teaches controlled publishing of learning content and sanitized analytics.
- You verify that exposure boundaries and security controls are enforced as part of deployment completion.

Run:
1. Follow CLOUDFLARE_DEPLOYMENT.md Lesson A and B for Pages + domain.
2. Follow Lesson C and D for tunnel + workers.
3. Follow Lesson E for auth, read-only DB role, and rate limits.

Checkpoint:
- Lesson site is accessible.
- API responds as expected.
- Database remains private.

---

## Fast Verification Commands
Use this block for routine health checks after changes or restarts. Each command targets one operational signal: resolver answer path, ingestor process health, raw data freshness, and rollup freshness. If one check fails, you can isolate the failing layer immediately.
```bash
# Resolver check
dig @127.0.0.1 cloudflare.com A

# Ingestor status
sudo systemctl status dns-ingestor --no-pager

# Fresh rows
psql -U dns_user -d dns_analytics -h localhost -c "SELECT MAX(queried_at) FROM dns_queries;"

# Rollup freshness
psql -U dns_user -d dns_analytics -h localhost -c "SELECT MAX(stat_date) FROM dns_daily_stats;"
```

---

## Completion Standard
You are considered fully onboarded when all are true:
1. Resolver is stable and logging.
2. Ingestor continuously writes to PostgreSQL.
3. Daily rollups are current.
4. You can interpret at least three analytics lessons.
5. In MikroTik mode, codeandcore.home records resolve and are analyzed.

---

## What to Open Next
1. index.html if you want full step-by-step teaching.
2. SQL_QUERIES.md if you want guided analytics practice.
3. CLOUDFLARE_DEPLOYMENT.md if you want edge publishing and secure API access.