সম্পূর্ণ ডেভেলপার গাইড

১. প্রকল্প পরিচিতি

মনচিত্র বাংলাদেশের শিক্ষার্থীদের জন্য বাংলা-প্রথম, দ্বিভাষিক স্টাডি কম্প্যানিয়ন। এটি পাঠ্যক্রমভিত্তিক ডিজিটাল বইয়ের সঙ্গে পাঠ, ব্যক্তিগত নোট, অনুশীলন, অডিও ও বয়স-সচেতন স্টাডি স্পেস যুক্ত করে।

বর্তমান পাইলটটি দশম শ্রেণির পদার্থবিজ্ঞানের মৌলিক নমুনা অধ্যায়। এটি কোনো সরকারি পাঠ্যবইয়ের অনুলিপি বা অনুমোদন নয়। প্রকাশের আগে বিষয়-সম্পাদকদের পাঠ্যক্রমের সামঞ্জস্য ও কনটেন্টের অধিকার যাচাই করতে হবে।

• প্রধান ব্যবহারকারী: ষষ্ঠ–দ্বাদশ শ্রেণির শিক্ষার্থী; অভিভাবক, শিক্ষক, সম্পাদক ও প্রশাসক।
• পাঠ্যক্রম: প্রথমে NCTB বাংলা মাধ্যম, পাশাপাশি ইংরেজি ভার্সন।
• পণ্যের নীতি: শিক্ষার্থীর নিজস্ব চিন্তাকে প্রতিস্থাপন নয়, ব্যাখ্যা ও দিকনির্দেশে সহায়তা।

২. প্রযুক্তি স্ট্যাক

৩. ফ্রন্টএন্ড প্রকল্প কাঠামো

বর্তমান রিপোজিটরি একটি সংক্ষিপ্ত App Router ডেমো। নিচের কাঠামো বর্তমান এন্ট্রি পয়েন্ট ও পরবর্তী প্রোডাকশন ধাপের প্রস্তাবিত মডিউল আলাদা করে।

• রুট ফাইল সংক্ষিপ্ত রাখুন; পুনর্ব্যবহারযোগ্য কাজ components-এ এবং domain data lib-এ রাখুন।
• সার্ভার-অনলি key বা privileged database client ব্রাউজার bundle-এ প্রকাশ করবেন না।

app/
  app/                         # student overview
  onboarding/                  # profile setup demo
  library/                     # searchable sample catalog
  reader/[book]/               # flipbook reader
  practice/[chapter]/          # chapter quiz
  guardian/                    # consent-aware overview demo
  study-room/[room]/           # moderated local demo
  investors/                   # investor section
  documentation/               # developer docs and TOR
components/monchitro/
  chrome.tsx                   # public and student navigation
  reader.tsx                   # reader tools and local annotations
  reader-flipbook.tsx          # dynamic HTMLFlipBook wrapper
  practice.tsx                 # quiz and result state
  student.tsx                  # dashboard, library and guardian views
lib/
  monchitro-content.ts         # original bilingual sample content
  monchitro-docs.ts            # bilingual documentation data
  supabase/                    # server, browser and session clients (next phase)
public/
  manifest.webmanifest
  monchitro-sw.js
supabase/migrations/            # managed schema changes (MCP-applied)

৪. ফ্লিপবুক ডেভেলপমেন্ট স্পেসিফিকেশন

StPageFlip ব্রাউজারের layout API-নির্ভর হওয়ায় রিডারটি SSR বন্ধ রেখে dynamic import করা হয়। পৃষ্ঠা কম্পোনেন্টে React.forwardRef ও PageFlip API ব্যবহৃত হয়—CSS-ভিত্তিক নকল অ্যানিমেশন নয়।

• ডেস্কটপে landscape দুই পৃষ্ঠা এবং ছোট পর্দায় portrait এক পৃষ্ঠা ব্যবহার করুন।
• প্রত্যাশিত page count পাওয়ার পর controls সক্রিয় করুন; HTML পৃষ্ঠা প্রস্তুত হওয়ার আগেই ref তৈরি হতে পারে।
• parent-এর অগ্রগতি বদলালেও active page turn চলাকালে DOM বদলানো এড়াতে page children memoize করুন।
• নির্বাচনযোগ্য লেখা বজায় রাখুন; drag-এর জন্য page margin/corner রাখুন এবং keyboard/page control দিন।

• বাস্তব mouse drag, touch swipe, keyboard arrow এবং accessible আগের/পরের button যাচাই করুন।
• নির্ধারিত breakpoint-এ cover/back-cover hard density এবং দুই পৃষ্ঠা/portrait layout পরীক্ষা করুন।

const Flipbook = dynamic(() => import("./reader-flipbook"), { ssr: false })

const InnerPage = forwardRef<HTMLDivElement, PageProps>(function InnerPage(
  { page }, ref,
) {
  return <div ref={ref} className="reader-page" data-density="soft">
    <article>{page.title}<p>{page.body}</p></article>
  </div>
})

const CoverPage = forwardRef<HTMLDivElement, CoverProps>(function CoverPage(
  { title }, ref,
) {
  return <div ref={ref} className="reader-cover" data-density="hard">
    <h1>{title}</h1>
  </div>
})

<HTMLFlipBook
  ref={bookRef}
  width={440}
  height={620}
  size="stretch"
  minWidth={280}
  maxWidth={880}
  minHeight={390}
  maxHeight={620}
  showCover
  usePortrait={isMobile}
  mobileScrollSupport
  showPageCorners
  onFlip={(event) => setPageIndex(event.data)}
>
  {pageElements}
</HTMLFlipBook>

bookRef.current?.pageFlip().flipNext()
bookRef.current?.pageFlip().flipPrev()
bookRef.current?.pageFlip().turnToPage(index)

৫. পাঠ্যবই কনটেন্ট ইঞ্জিন

একটি বই হলো সংস্করণযুক্ত পাঠ্যক্রমভিত্তিক কনটেন্ট: বইয়ের metadata → অধ্যায়ক্রম → page record → নির্বাচনযোগ্য text node ও লাইসেন্সপ্রাপ্ত asset। বর্তমান reader typed bundled sample ব্যবহার করে; production publishing-এ প্রতিটি revision যাচাই ও audit trail রাখতে হবে।

• পাঠ্যক্রম, শ্রেণি, মাধ্যম/সংস্করণ, বিষয়, অধ্যায়, পৃষ্ঠা, ভাষা, revision এবং rights/source metadata রাখুন।
• diagram SVG বা optimized raster asset এবং text alternative-সহ রাখুন; lesson text image-এ flatten করবেন না।
• text-to-speech offset authored paragraph-এর সঙ্গে যুক্ত করুন, screen coordinate-এর সঙ্গে নয়।
• শুধু স্পষ্ট download action-এর পর অধ্যায় cache করুন এবং storage/version state দেখান।

৬. সহযোগী annotation স্থাপত্য

highlight, private note, public comment ও shared-room cursor আলাদা ডেটা শ্রেণি। বর্তমান reader local component state-এ annotation রাখে; production adapter-এ private record user-ভিত্তিক এবং shared content room membership-ভিত্তিক অনুমোদিত হতে হবে।

• একটি Y.Doc-এ room-এর ordered comment ও shared highlight থাকতে পারে; private note ওই shared document-এর বাইরে রাখুন।
• WebSocket provider সক্রিয় করার আগে server-authorized room token, membership check, rate limit ও moderation ব্যবহার করুন।
• synchronization-কে durable বলার আগে snapshot, retention, replay ও deletion behavior নির্ধারণ করুন।

৭. AI শিক্ষক ইন্টিগ্রেশন

AI শিক্ষক শিক্ষার্থীর যুক্তি গঠনে সহায়তা করবে: প্রশ্ন স্পষ্ট করবে, জানা রাশি চিহ্নিত করবে, একবারে একটি hint দেবে এবং যাচাইকৃত পাঠ্যপাতায় ফিরিয়ে নেবে। তৈরি করা ব্যাখ্যাকে নীরবে যাচাইকৃত পাঠ্যক্রম কনটেন্ট হিসেবে জমা দেবেন না।

• সার্ভার route থেকে Vercel AI Gateway কল করুন; model identifier ও prompt সার্ভারে রাখুন।
• শুধু নির্বাচিত text ও প্রয়োজনীয় chapter context পাঠান; শিক্ষার্থীর পরিচয়সংক্রান্ত অপ্রয়োজনীয় তথ্য বাদ দিন।
• request size limit, user/IP rate limit, output moderation এবং report-answer পথ রাখুন।
• AI অনুপলব্ধ হলে sample hint-কে demo content বলুন; live model response বলে দাবি করবেন না।

৮. মূল্যায়ন ইঞ্জিন

• question bank version করুন; prompt, option, সঠিক উত্তর, ব্যাখ্যা, নম্বর, topic, difficulty, locale ও publication status রাখুন।
• authenticated attempt-এর score সার্ভারে হিসাব করুন; client-supplied score-কে authoritative হিসেবে গ্রহণ করবেন না।
• একটি unique attempt ID, answer map, সময়, score ও question version-সহ attempt একবার persist করুন।
• নির্বাচিত উত্তর, সঠিক উত্তর ও বয়স-উপযোগী ব্যাখ্যাসহ review দেখান।

৯. ডেটাবেস নকশা

UUID primary key, স্পষ্ট foreign key, timestamp এবং সাধারণ query path-এর জন্য নির্দিষ্ট index ব্যবহার করুন। শিক্ষার্থী/অভিভাবকের তথ্য থাকা প্রতিটি table-এ RLS চালু করতে হবে। এই guide তৈরির সময় live Supabase project খালি ছিল; runtime code ব্যবহারের আগে migration প্রয়োগ ও পর্যালোচনা করুন।

alter table public.annotations enable row level security;

create policy annotations_select_own
on public.annotations for select
using (auth.uid() = user_id);

create policy annotations_insert_own
on public.annotations for insert
with check (auth.uid() = user_id);

১০. API ডকুমেন্টেশন

নিচের route-গুলো প্রস্তাবিত contract নির্ধারণ করে। এগুলো specification—প্রতিটি endpoint বাস্তবায়িত বা deployed বলে দাবি নয়।

POST /api/annotations
Authorization: Bearer <Supabase access token>
Content-Type: application/json

{
  "pageId": "uuid",
  "kind": "highlight",
  "selectedText": "A net force changes motion.",
  "color": "sunshine"
}

১১. PWA ও অফলাইন ইঞ্জিনিয়ারিং

• app name, standalone display, theme color ও আসল icon asset-সহ বৈধ web manifest দিন।
• app shell ও স্পষ্টভাবে download করা chapter data cache করুন; private API response public cache-এ রাখবেন না।
• schema version ও size-aware deletion-সহ IndexedDB ব্যবহার করুন; download progress ও offline availability দেখান।
• শুধু retry-safe progress write queue করুন; device reconnect হলে conflict reconcile করুন।
• iOS-এ Safari Share → Add to Home Screen বুঝিয়ে দিন; App Store listing আছে বলে দাবি করবেন না।

১২. নিরাপত্তা ও গোপনীয়তা

• Supabase service-role ও AI credential কেবল সার্ভারে রাখুন।
• RLS চালু করে প্রতিটি private read/write auth.uid()-এ সীমাবদ্ধ করুন; guardian relationship parent level-এ যাচাই করুন।
• প্রয়োজনীয় ন্যূনতম বয়স/সম্মতি তথ্য নিন; শিক্ষার্থীর contact, school identifier বা নির্দিষ্ট অবস্থান প্রকাশ করবেন না।
• private note ডিফল্টভাবে ব্যক্তিগত; অভিভাবক কেবল সম্মতিসূচক summary পাবেন।
• subscription-কে paid বলার আগে server-side payment verification ও idempotency ব্যবহার করুন।
• peer space চালুর আগে moderation, report, block, mute, retention, export ও deletion ব্যবস্থা করুন।

১৩. Deployment ও DevOps

• পর্যালোচিত Git branch ও pull request ব্যবহার করুন; production-এর আগে preview deploy করুন।
• Vercel-এ কেবল প্রয়োজনীয় environment variable দিন; source বা documentation-এ secret রাখবেন না।
• অনুমোদিত Supabase migration workflow দিয়ে schema দিন এবং release-এর আগে RLS যাচাই করুন।
• error rate, route latency, AI usage, storage ও ব্যর্থ background কাজ monitor করুন।
• data backup, restore test এবং incident, rollback ও security-contact প্রক্রিয়া নির্ধারণ করুন।

• বাংলা ও ইংরেজিতে preview smoke test
• RLS ও role boundary পরীক্ষা
• mobile reader, PWA ও offline পরীক্ষা
• কনটেন্ট অধিকার ও পাঠ্যক্রম পর্যালোচনা
• rollback ও support owner নিশ্চিত