# PatternAlign Studio — Deployment Guide

এই প্যাকেজটি সম্পূর্ণ static: কোনো build step, Node runtime, environment variable বা database ছাড়াই চলে। এতে **পাঁচটি অ্যাপ** আছে: PatternAlign Studio, ভূমি ইঞ্জিন, KMZ দাগ ম্যাপার, AnyShape Divider এবং ম্যাপ জয়েন্ট (v4)। সবগুলো একই ফোল্ডারে রাখলে টুল হাব ও এমবেডেড ভিউয়ার কাজ করবে।

## 1. প্যাকেজে কী আছে

| ফাইল | কাজ |
|---|---|
| `index.html` | PatternAlign Studio — প্রধান অ্যাপ (editor, geometry, IndexedDB, export) |
| `bhumi-engine.html` | ভূমি পরিমাপ ও ভাগবণ্টন ইঞ্জিন (প্রোটোটাইপ) |
| `kmz-engine.html` | স্যাটেলাইট দাগ ম্যাপার ও Google Earth KMZ Maker |
| `anyshape-divider.html` | AnyShape Divider — যেকোনো আকৃতির জমি ভাগ, রাস্তা ও রিপোর্ট |
| `map-joint.html` | ভূমি ইঞ্জিন v4 — ম্যাপ জয়েন্ট (মাল্টি-শিট পointing, স্টিচিং, QC) |
| `joint-sw.js` | ম্যাপ জয়েন্টের offline service worker |
| `sw.js` | Service worker — অফলাইন ক্যাশ ও PWA |
| `manifest.webmanifest` | PWA নাম, আইকন, shortcuts, theme |
| `icons/icon.svg` | অরিজিনাল অ্যাপ আইকন (runtime-এ PNG আইকনও তৈরি হয়) |
| `404.html` | ব্র্যান্ডেড নট-ফাউন্ড পেজ |
| `_headers` | Netlify / Cloudflare Pages security ও cache headers |
| `netlify.toml` | Netlify publish config |
| `vercel.json` | Vercel cache/security headers |
| `.htaccess` | Apache / cPanel cache, MIME ও SPA-related config |
| `.nojekyll` | GitHub Pages যেন ফাইল/ফোল্ডার বাদ না দেয় |
| `wrangler.toml` | Cloudflare Pages CLI config |
| `README.md` | ফিচার, ইঞ্জিন, সীমাবদ্ধতা |
| `DEPLOY.md` | এই নির্দেশিকা |
| `BUILD-INFO.txt` | ZIP তৈরির সময় স্বয়ংক্রিয়ভাবে তৈরি: সংস্করণ, সময়, ২০ ফাইলের তালিকা ও কোনটি live/fallback/missing |
| `make-zip.sh` | পাঁচটি অ্যাপসহ পূর্ণ deployment ZIP তৈরির স্ক্রিপ্ট (`bash make-zip.sh`) |

## 2. Cloudflare Pages বনাম Netlify — কোনটি বেছে নেবেন?

এই অ্যাপটি **সম্পূর্ণ static** (কোনো সার্ভার কোড, database বা build step নেই)। তাই দুটোই চলে, কিন্তু অগ্রাধিকার আলাদা।

| বিষয় | Cloudflare Pages (Free) | Netlify (Free) |
|---|---|---|
| Static bandwidth | **আনলিমিটেড** | ১০০ GB/মাস, এরপর সাইট পজ হতে পারে |
| Static requests | আনলিমিটেড | সীমার মধ্যে |
| Build | ৫০০/মাস (এই অ্যাপে build লাগেই না) | ৩০০ build মিনিট/মাস |
| ফাইল সীমা | ২০,০০০ ফাইল, প্রতি ফাইল ২৫ MiB | সাধারণত যথেষ্ট |
| CDN | ৩০০+ POP, ঢাকায় POP আছে | ভালো, তবে এশিয়ায় তুলনামূলক কম POP |
| Custom domain + SSL | ফ্রি | ফ্রি |
| Analytics | Cloudflare Web Analytics ফ্রি | আলাদা पेড অ্যাড-অন |
| DDoS সুরক্ষা | ডিফল্ট, খুব শক্তিশালী | ভালো |
| ডিপ্লয়ের সহজতা | ড্র্যাগ করে আপলোড বা CLI | **সবচেয়ে সহজ Drag & Drop (Netlify Drop)** |
| পেমেন্ট/কার্ড | ফ্রি প্ল্যানে লাগে না | ফ্রি প্ল্যানে লাগে না |
| কমার্শিয়াল ব্যবহার | অনুমোদিত | অনুমোদিত (Vercel Hobby-তে নয়) |

**এই প্রজেক্টের সুপারিশ:**
1. দীর্ঘমেয়াদি/পাবলিক প্রোডাকশনের জন্য **Cloudflare Pages**—আনলিমিটেড ব্যান্ডউইথ, বাংলাদেশে ভালো গতি, ফ্রি অ্যানালিটিক্স।
2. শুধু দ্রুত ডেমো/ক্লায়েন্টকে লিংক দেখানোর জন্য **Netlify Drop**—৩০ সেকেন্ডে লাইভ।
3. দুটোতেই একই ZIP ব্যবহার করুন; কোনো কোড বদলাতে হবে না।

> গুরুত্বপূর্ণ: অ্যাপে সব ইমেজ প্রসেসিং ক্লায়েন্টে হয়, তাই হোস্টিংয়ে কোনো ইউজার ফাইল যায় না। বড় ট্রাফিকেও Cloudflare-এ বিল আসবে না, কারণ static asset unmetered।

## 2.1 Cloudflare Pages-এ ডিপ্লয় (প্রস্তাবিত)

**পদ্ধতি A — ড্যাশবোর্ড (সহজ):**
1. **Settings → ডিপ্লয় প্যাকেজ → ZIP ডাউনলোড** চাপুন।
2. <https://dash.cloudflare.com/> → **Workers & Pages** → **Create** → **Pages** → **Upload assets**।
3. প্রকল্পের নাম দিন (যেমন `patternalign-studio`) → ZIP বা unzipped ফোল্ডার আপলোড করুন।
4. **Deploy site** → `https://patternalign-studio.pages.dev` লিংক পাবেন।
5. **Custom domain** → নিজের ডোমেইন যোগ করুন; SSL অটো।

**পদ্ধতি B — CLI:**
```bash
# unzip করা ফোল্ডারে
npx wrangler pages deploy .
```
`wrangler.toml` ইতিমধ্যে আছে (`pages_build_output_dir = "."`)।

**Cloudflare সেটিংস:**
- Build command: ফাঁকা
- Build output directory: `/` বা `.`
- Framework preset: None
- `_headers` স্বয়ংক্রিয়ভাবে পড়বে (sw.js no-cache, security headers)

**লক্ষ্য রাখুন:** Cloudflare নতুন ফুল-স্ট্যাক প্রজেক্টের জন্য Workers static assets-এ যাচ্ছে। আমাদের অ্যাপের জন্য Pages এখনো পুরোপুরি ঠিক আছে এবং কোনো Function ব্যবহার করছে না।

## 2.2 Netlify-তে ডিপ্লয় (দ্রুত ডেমো)

1. <https://app.netlify.com/drop> খুলুন।
2. ZIP ফাইলটি (বা unzipped ফোল্ডার) ড্র্যাগ করুন।
3. লাইভ HTTPS URL পাওয়ার সাথে সাথে PWA ইনস্টল ও service worker কাজ করবে।
4. দরকার হলে **Site settings → Domain management** থেকে কাস্টম ডোমেইন যোগ করুন।

> ZIP-এর ভেতরে ফাইলগুলো root-এ থাকা দরকার। এই প্যাকেজে `index.html` root-এ আছে, তাই সরাসরি ড্র্যাগ করা যাবে।

## 3. Vercel

```bash
# unzip করার পর ফোল্ডারের ভিতরে
npx vercel --prod
```

- Framework preset: **Other**
- Build command: ফাঁকা
- Output directory: `.`
- `vercel.json` ইতিমধ্যে `sw.js` no-cache ও নিরাপত্তা হেডার দেয়।

## 4. GitHub Pages

```bash
git init
git add index.html sw.js manifest.webmanifest icons README.md DEPLOY.md 404.html
git commit -m "Deploy PatternAlign Studio"
git branch -M main
git remote add origin https://github.com/USERNAME/REPO.git
git push -u origin main
```

GitHub → **Settings → Pages → Build and deployment → Deploy from a branch → main / root**।

সমস্যা প্রতিরোধ:
- `index.html`-এ manifest ও service worker **relative path** ব্যবহার করে, তাই subpath (`/repo-name/`) কাজ করে।
- `.nojekyll` ফাইল যোগ করলে GitHub Pages underscore-শুরু ফাইল/ফোল্ডার বাদ দেবে না:
  ```bash
  touch .nojekyll
  ```
  (ZIP প্যাকেজে এটি নেই; দরকার হলে যোগ করুন।)
- GitHub Pages HTTPS দেয়, তাই install prompt আসবে।

## 5. Cloudflare Pages

- Framework preset: **None**
- Build command: ফাঁকা
- Build output directory: `/` (রুট)
- `_headers` স্বয়ংক্রিয়ভাবে পড়া হবে।

## 6. cPanel / Apache (shared hosting)

1. ZIP unzip করুন যেন `index.html` `public_html/`-এ থাকে।
2. `icons/` ফোল্ডার ও বাকি ফাইলও আপলোড করুন।
3. `index.html` ঠিক আছে কি না দেখুন: `https://example.com/`
4. SSL ইনস্টল করে `https://` চালু করুন। `.htaccess`-এ কমেন্ট করা HTTPS redirect চালু করতে পারেন।
5. `.htaccess` ফাইলটি hidden; File Manager-এ "Show Hidden Files" চালু করুন।

## 7. Nginx (নমুনা)

```nginx
server {
  listen 443 ssl http2;
  server_name example.com;
  root /var/www/patternalign;
  index index.html;

  location = /sw.js {
    add_header Cache-Control "no-cache, no-store, must-revalidate";
    add_header Service-Worker-Allowed "/";
    try_files $uri =404;
  }
  location = /manifest.webmanifest {
    types { } default_type application/manifest+json;
    add_header Cache-Control "public, max-age=3600";
  }
  location /icons/ {
    add_header Cache-Control "public, max-age=604800, immutable";
  }
  location = /index.html {
    add_header Cache-Control "public, max-age=0, must-revalidate";
  }
  location / {
    try_files $uri $uri/ =404;
  }
}
```

## 8. PWA ও অফলাইন

- **HTTPS বা localhost** ছাড়া service worker ইনস্টল হয় না। `file://`-এ খুললে অ্যাপ চলবে, কিন্তু offline cache ও install prompt আসবে না।
- প্রথমবার অনলাইনে লোড হলে ফন্ট, PDF লাইব্রেরি ও অ্যাপ শেল ক্যাশ হয়। এরপর সম্পাদনা ও লোকাল সেভ অফলাইনে কাজ করে।
- নতুন সংস্করণ deploy করলে `sw.js`-এর `VERSION` বদলান (যেমন `pa-v1.1.0` → `pa-v1.2.0`)। পুরোনো ক্যাশ activate-এ পরিষ্কার হবে।
- Install prompt ব্রাউজার-নির্ভর। Settings → ইনস্টলেশন-এ Android/iOS/Desktop নির্দেশনা আছে।

## 9. ডেটা ও প্রাইভেসি

- প্রকল্প, ছবি, মাস্ক, মাপ—সব **এই ব্রাউজারের IndexedDB**-তে। কোনো সার্ভার বা অ্যাকাউন্ট নেই।
- ব্রাউজার ডেটা মুছে ফেললে বা private window বন্ধ করলে লোকাল কাজ হারাতে পারে। নিয়মিত **Project JSON** export/backup নিন।
- ছবি বা নমুনা কোনো তৃতীয় পক্ষের সার্ভারে আপলোড হয় না।
- CDN নির্ভরতা: Google Fonts, Tailwind browser CDN, jsPDF (PDF-এর জন্য)। এগুলো blocked থাকলে মূল CSS/ইঞ্জিন এখনো কাজ করবে; PDF না হলে ব্রাউজার-প্রিন্ট ফলব্যাক রয়েছে।

## 10. হেডার ও ক্যাশিং

`_headers` / `vercel.json` / `.htaccess` ইতিমধ্যে Includes:
- `X-Content-Type-Options: nosniff`
- `X-Frame-Options: SAMEORIGIN`
- `Referrer-Policy`, `Permissions-Policy`
- `index.html`: must-revalidate
- `sw.js`: no-cache
- `manifest`: `application/manifest+json`
- `icons`: 7 দিন cache

CSP যোগ করলে inline script/style ও CDN API অনুমতি দিতে হবে; ভুল CSP দিলে অ্যাপ ভেঙে যাবে, তাই ইচ্ছাকৃতভাবে বাদ দেওয়া হয়েছে।

## 11. আপডেট ও রোলব্যাক

- স্ট্যাটিক হোস্টে পুরোনো ZIP/ফোল্ডার রেখে শুধু `index.html`, `sw.js` ও প্রয়োজনীয় ফাইল replace করুন।
- `sw.js` version না বদলালে ব্যবহারকারী পুরোনো ক্যাশ পেতে পারে।
- ভাঙা deploy হলে আগের ZIP পুনরায় upload করুন; লোকাল проект ডেটা ব্রাউজারে থেকেই যাবে।

## 12. ডিপ্লয়ের আগে চেকলিস্ট

- [ ] `index.html` root-এ আছে
- [ ] `sw.js` root-এ আছে (index.html-এর পাশে)
- [ ] `manifest.webmanifest` ও `icons/icon.svg` আছে
- [ ] HTTPS সক্রিয়
- [ ] DevTools → Application → Manifest: কোনো error নেই
- [ ] DevTools → Application → Service Workers: activated
- [ ] হোম স্ক্রিনে install করে অফলাইনে খোলা যায়
- [ ] নতুন প্রকল্প → দুটি ডিজাইন → রঙিন ওভারলে → PNG/PDF export
- [ ] JSON export করে অন্য ব্রাউজারে import

## 13. ইন-অ্যাপ ZIP ডাউনলোড — সম্পূর্ণতা যাচাই

অ্যাপের **Dashboard → ডিপ্লয় প্যাকেজ** বা **Settings → ডিপ্লয় প্যাকেজ → ZIP ডাউনলোড** চেপে `bhumiporimap-suite-deploy.zip` নামান। এতে **২০টি ফাইল ও পাঁচটি অ্যাপ** থাকে:

```
index.html  bhumi-engine.html  kmz-engine.html
anyshape-divider.html  map-joint.html
sw.js  joint-sw.js  manifest.webmanifest  icons/icon.svg
404.html  _headers  netlify.toml  vercel.json  .htaccess  .nojekyll
wrangler.toml  README.md  DEPLOY.md  make-zip.sh  BUILD-INFO.txt
```

ডাউনলোডের পর:
1. ZIP-এর ভেতরের **`BUILD-INFO.txt`** খুলুন।
2. `VERSION: 1.5.0` এবং `APPS: 5` আছে কি না দেখুন।
3. শেষ লাইনে `OK: all five product apps are included` আছে কি না দেখুন।
4. কোনো অ্যাপ `WARNING`-এ থাকলে **Settings → আলাদা ফাইল ডাউনলোড** ব্যবহার করুন, অথবা প্রকল্প ফোল্ডারে `bash make-zip.sh` চালান।

কোনো build service বা Node.js ছাড়াই ZIP তৈরি হয়; এটি ZIP-এর store মেথড (BEGIN/END signature, CRC32) ব্যবহার করে, তাই ফাইলটি যেকোনো unzip টুলে খোলে। যদি কোনো হোস্ট sibling ফাইল fetch করতে ব্লক করে, অ্যাপ এখন জোরালোভাবে সেটি জানায় এবং BUILD-INFO-তে তালিকাভুক্ত করে—নীরবে অসম্পূর্ণ প্যাকেজ দেয় না।

CLI পদ্ধতি (যদি রিপো ক্লোন করা থাকে):

```bash
bash make-zip.sh
```

লাইসেন্স/ব্র্যান্ড: এই অ্যাপের কোড, UI ও ডেমো আর্টওয়ার্ক অরিজিনাল। কোনো বিদ্যমান পণ্যের ব্র্যান্ড, লোগো বা মালিকানাধীন অ্যাসেট ব্যবহার করা হয়নি।