# AGENTS.md

## প্রকল্পের ওভারভিউ

এটি শিক্ষণীয় কারিকুলাম রিপোজিটরি যা শুরু কারীদের জন্য ওয়েব ডেভেলপমেন্টের মূল বিষয়গুলো শেখানোর জন্য তৈরি। এই কারিকুলাম একটি সমন্বিত ১২ সপ্তাহের কোর্স যা Microsoft Cloud Advocates দ্বারা তৈরি, যার মধ্যে ২৪টি হাতে-কলমে শেখানো পাঠ রয়েছে যেগুলো JavaScript, CSS এবং HTML আচ্ছাদিত।

### প্রধান উপাদানসমূহ

- **শিক্ষণীয় বিষয়বস্তু**: ২৪টি গঠনমূলক পাঠ প্রকল্পভিত্তিক মডিউলে বিন্যস্ত
- **প্রায়োগিক প্রকল্পসমূহ**: Terrarium, Typing Game, Browser Extension, Space Game, Banking App, Code Editor এবং AI Chat Assistant
- **ইন্টারেক্টিভ কুইজ**: ৪৮টি কুইজ প্রতি ৩টি প্রশ্ন নিয়ে (পাঠের আগে/পাঠের পরে মূল্যায়ন)
- **বহুভাষিক সাপোর্ট**: GitHub Actions এর মাধ্যমে ৫০+ ভাষার স্বয়ংক্রিয় অনুবাদ
- **প্রযুক্তিসমূহ**: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (AI প্রকল্পের জন্য)

### স্থাপত্য

- পাঠভিত্তিক গঠন সহ শিক্ষণীয় রিপোজিটরি
- প্রতিটি পাঠের ফোল্ডারে README, কোড উদাহরণ এবং সমাধান রয়েছে
- পৃথক ডিরেক্টরিতে স্বতন্ত্র প্রকল্পসমূহ (quiz-app, বিভিন্ন পাঠ প্রকল্প)
- GitHub Actions (co-op-translator) ব্যবহার করে অনুবাদ ব্যবস্থা
- Docsify দ্বারা ডকুমেন্টেশন পরিবেশন এবং PDF আকারে উপলব্ধ

## সেটআপ কমান্ডসমূহ

এই রিপোজিটরি মূলত শিক্ষণীয় বিষয়বস্তু ব্যবহারের জন্য। নির্দিষ্ট প্রকল্পের জন্য কাজ করতে:

### মূল রিপোজিটরি সেটআপ

```bash
git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
cd Web-Dev-For-Beginners
```

### Quiz App সেটআপ (Vue 3 + Vite)

```bash
cd quiz-app
npm install
npm run dev        # ডেভেলপমেন্ট সার্ভার শুরু করুন
npm run build      # প্রোডাকশনের জন্য বিল্ড করুন
npm run lint       # ESLint চালান
```

### ব্যাংক প্রকল্প API (Node.js + Express)

```bash
cd 7-bank-project/api
npm install
npm start          # এপি আই সেবা শুরু করুন
npm run lint       # ESLint চালান
npm run format     # Prettier দিয়ে ফরম্যাট করুন
```

### ব্রাউজার এক্সটেনশন প্রকল্পসমূহ

```bash
cd 5-browser-extension/solution
npm install
# ব্রাউজার-নির্দিষ্ট এক্সটেনশন লোড করার নির্দেশিকা অনুসরণ করুন
```

### স্পেস গেম প্রকল্পসমূহ

```bash
cd 6-space-game/solution
npm install
# ব্রাউজারে index.html খুলুন অথবা লাইভ সার্ভার ব্যবহার করুন
```

### চ্যাট প্রকল্প (Python ব্যাকএন্ড)

```bash
cd 9-chat-project/solution/backend/python
pip install openai
# GITHUB_TOKEN পরিবেশ ভেরিয়েবল সেট করুন
python api.py
```

## উন্নয়ন কার্যপ্রবাহ

### বিষয়বস্তু অবদানকারীদের জন্য

1. **রিপোজিটরি ফর্ক করুন** আপনার GitHub অ্যাকাউন্টে
2. **আপনার ফর্ক ক্লোন করুন** লোকালি
3. **আপনার পরিবর্তনের জন্য নতুন ব্রাঞ্চ তৈরি করুন**
4. পাঠের বিষয়বস্তু বা কোড উদাহরণে পরিবর্তন করুন
5. প্রাসঙ্গিক প্রকল্প ডিরেক্টরিতে কোড পরিবর্তন পরীক্ষা করুন
6. অবদান নীতিমালা অনুসরণ করে pull request জমা দিন

### শিক্ষার্থীদের জন্য

1. রিপোজিটরি ফর্ক বা ক্লোন করুন
2. পাঠের ডিরেক্টরিগুলো ধারাবাহিকভাবে নেভিগেট করুন
3. প্রতিটি পাঠের README ফাইল পড়ুন
4. https://ff-quizzes.netlify.app/web/ এ পাঠের আগে কুইজ সম্পূর্ণ করুন
5. পাঠের ফোল্ডারে কোড উদাহরণগুলো অনুসরণ করুন
6. অ্যাসাইনমেন্ট এবং চ্যালেঞ্জ সম্পূর্ণ করুন
7. পাঠের পরে কুইজ দিন

### লাইভ ডেভেলপমেন্ট

- **ডকুমেন্টেশন**: রুটে `docsify serve` চালান (পোর্ট ৩০০০)
- **Quiz App**: quiz-app ডিরেক্টরিতে `npm run dev` চালান
- **প্রকল্পসমূহ**: HTML প্রকল্পের জন্য VS Code Live Server এক্সটেনশন ব্যবহার করুন
- **API প্রকল্পসমূহ**: সংশ্লিষ্ট API ডিরেক্টরিতে `npm start` চালান

## টেস্টিং নির্দেশিকা

### Quiz App টেস্টিং

```bash
cd quiz-app
npm run lint       # কোড স্টাইল সমস্যা পরীক্ষা করুন
npm run build      # নিশ্চিত করুন বিল্ড সফল হয়েছে
```

### Bank API টেস্টিং

```bash
cd 7-bank-project/api
npm run lint       # কোড স্টাইল সমস্যার জন্য পরীক্ষা করুন
node server.js     # নিশ্চিত করুন যে সার্ভার ত্রুটি ছাড়াই শুরু হয়
```

### সাধারণ টেস্টিং পদ্ধতি

- এটি একটি শিক্ষণীয় রিপোজিটরি, ব্যাপক স্বয়ংক্রিয় টেস্ট নেই
- ম্যানুয়াল টেস্টিং কেন্দ্রীভূত:
  - কোড উদাহরণ ত্রুটিমুক্ত চালানো
  - ডকুমেন্টেশনের লিঙ্ক কাজ করছে কি না
  - প্রকল্প বিল্ড সফলভাবে সম্পন্ন হয়েছে
  - উদাহরণগুলি সেরা চর্চা অনুসরণ করছে

### সাবমিশনের আগে পরীক্ষা

- যেসব ডিরেক্টরিতে package.json আছে সেখানে `npm run lint` চালান
- মার্কডাউন লিঙ্ক সব সঠিক কিনা পরীক্ষা করুন
- কোড উদাহরণ ব্রাউজার বা Node.js এ পরীক্ষা করুন
- অনুবাদ কাঠামো ঠিক আছে কিনা দেখুন

## কোড স্টাইল নির্দেশিকা

### JavaScript

- আধুনিক ES6+ সিনট্যাক্স ব্যবহার করুন
- প্রকল্পের দেওয়া ESLint কনফিগারেশন অনুসরণ করুন
- শিক্ষার্থীদের জন্য অর্থবহ ভেরিয়েবল এবং ফাংশন নাম ব্যবহার করুন
- ধারণাগুলো ব্যাখ্যার জন্য মন্তব্য যোগ করুন
- প্রয়োজনমতো Prettier ব্যবহার করে ফরম্যাট করুন

### HTML/CSS

- সেম্যান্টিক HTML5 উপাদান ব্যবহার করুন
- রেস্পন্সিভ ডিজাইন নীতিমালা অনুসরণ করুন
- পরিষ্কার ক্লাস নামকরণ
- CSS কৌশল ব্যাখ্যা করতে মন্তব্য যোগ করুন শিক্ষার্থীদের জন্য

### Python

- PEP 8 স্টাইল গাইড অনুসরণ করুন
- পরিষ্কার, শিক্ষামূলক কোড উদাহরণ
- শিক্ষার্থীদের জন্য প্রয়োজনীয় ক্ষেত্রে টাইপ হিন্ট ব্যবহার করুন

### মার্কডাউন ডকুমেন্টেশন

- স্পষ্ট শিরোনাম স্তর
- ভাষা নির্দিষ্ট কোড ব্লক
- অতিরিক্ত রিসোর্স লিঙ্ক
- `images/` ফোল্ডারে স্ক্রিনশট এবং ইমেজ
- অ্যাক্সেসিবিলিটির জন্য ইমেজের জন্য Alt টেক্সট

### ফাইল সংগঠন

- পাঠগুলো ধারাবাহিকভাবে নাম্বার করা (1-getting-started-lessons, 2-js-basics ইত্যাদি)
- প্রতিটি প্রকল্পে `solution/` ও প্রায়ই `start/` বা `your-work/` ডিরেক্টরি থাকে
- ইমেজগুলো পাঠভিত্তিক `images/` ফোল্ডারে সঞ্চিত
- অনুবাদ `translations/{language-code}/` কাঠামোতে থাকে

## বিল্ড এবং ডিপ্লয়মেন্ট

### Quiz App ডিপ্লয়মেন্ট (Azure Static Web Apps)

quiz-app Azure Static Web Apps ডিপ্লয়মেন্টের জন্য কনফিগার করা হয়েছে:

```bash
cd quiz-app
npm run build      # dist/ ফোল্ডার তৈরি করে
# main এ push করলে GitHub Actions workflow এর মাধ্যমে ডিপ্লয় করে
```

Azure Static Web Apps কনফিগারেশন:
- **অ্যাপ লোকেশন**: `/quiz-app`
- **আউটপুট লোকেশন**: `dist`
- **ওয়ার্কফ্লো**: `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml`

### ডকুমেন্টেশন PDF তৈরি

```bash
npm install                    # docsify-to-pdf ইন্সটল করুন
npm run convert               # ডকুমেন্ট থেকে পিডিএফ জেনারেট করুন
```

### Docsify ডকুমেন্টেশন

```bash
npm install -g docsify-cli    # গ্লোবালি Docsify ইনস্টল করুন
docsify serve                 # localhost:3000 এ সার্ভ করুন
```

### প্রকল্প-নির্দিষ্ট বিল্ডসমূহ

প্রতিটি প্রকল্প ডিরেক্টরির নিজস্ব বিল্ড প্রক্রিয়া থাকতে পারে:
- Vue প্রকল্প: `npm run build` দিয়ে প্রোডাকশন বান্ডল তৈরি
- স্ট্যাটিক প্রকল্প: কোনো বিল্ড স্টেপ নেই, সরাসরি ফাইল সেবা

## পুল রিকোয়েস্ট গাইডলাইন

### শিরোনামের ফরম্যাট

পরিবর্তনের ক্ষেত্র স্পষ্ট করার জন্য পরিষ্কার ও বর্ণনামূলক শিরোনাম ব্যবহার করুন:
- `[Quiz-app] পাঠ এক্স এর জন্য নতুন কুইজ যোগ করুন`
- `[Lesson-3] Terrarium প্রকল্পের টাইপো সংশোধন`
- `[Translation] পাঠ ৫ জন্য স্প্যানিশ অনুবাদ যুক্ত করুন`
- `[Docs] সেটআপ নির্দেশিকা আপডেট`

### প্রয়োজনীয় পরীক্ষা

PR জমা দেওয়ার আগে:

1. **কোড মান**:
   - সংশ্লিষ্ট প্রকল্প ডিরেক্টরিতে `npm run lint` চালান
   - সব লিন্ট ত্রুটি ও সতর্কতা ঠিক করুন

2. **বিল্ড যাচাই**:
   - প্রযোজ্য হলে `npm run build` চালান
   - নিশ্চিত করুন কোনো বিল্ড ত্রুটি নেই

3. **লিঙ্ক যাচাই**:
   - সমস্ত মার্কডাউন লিঙ্ক পরীক্ষা করুন
   - ইমেজ রেফারেন্স সঠিক আছে কিনা নিশ্চিত করুন

4. **বিষয়বস্তু পর্যালোচনা**:
   - বানান এবং ব্যাকরণ পরীক্ষা করুন
   - কোড উদাহরণ সঠিক ও শিক্ষামূলক কিনা নিশ্চিত করুন
   - অনুবাদগুলি মূল অর্থ বজায় রাখে কিনা যাচাই করুন

### অবদান শর্তসমূহ

- Microsoft CLA তে সম্মত হতে হবে (প্রথম PR এ স্বয়ংক্রিয় পরীক্ষা)
- [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/) অনুসরণ করতে হবে
- বিস্তারিত নির্দেশিকার জন্য [CONTRIBUTING.md](./CONTRIBUTING.md) দেখুন
- প্রয়োজন হলে PR বিবরণে ইস্যু নম্বর উল্লেখ করুন

### পর্যালোচনা প্রক্রিয়া

- PR পর্যালোচনা করেন রক্ষণাবেক্ষক ও সম্প্রদায়
- শিক্ষাগত স্পষ্টতা অগ্রাধিকার পায়
- কোড উদাহরণ বর্তমান সেরা চর্চা অনুসরণ করে তা নিশ্চিত করুন
- অনুবাদ সঠিকতা ও সাংস্কৃতিক উপযুক্ততা যাচাই হয়

## অনুবাদ ব্যবস্থা

### স্বয়ংক্রিয় অনুবাদ

- GitHub Actions এর co-op-translator ওয়ার্কফ্লো ব্যবহার করে
- ৫০+ ভাষায় স্বয়ংক্রিয় অনুবাদ করে
- মূলে ফাইল প্রধান ডিরেক্টরিতেই থাকে
- অনূদিত ফাইল থাকে `translations/{language-code}/` ডিরেক্টরিতে

### ম্যানুয়াল অনুবাদ উন্নতি যোগ করা

1. `translations/{language-code}/` এ ফাইল অবস্থান নির্ণয় করুন
2. কাঠামো বজায় রেখে উন্নতি করুন
3. কোড উদাহরণ কাজ করছে কিনা নিশ্চিত করুন
4. লোকালাইজড কুইজ বিষয়বস্তু পরীক্ষা করুন

### অনুবাদের মেটাডাটা

অনূদিত ফাইলগুলিতে মেটাডাটা হেডার অন্তর্ভুক্ত থাকে:
```markdown
<!--
CO_OP_TRANSLATOR_METADATA:
{
  "original_hash": "...",
  "translation_date": "...",
  "source_file": "...",
  "language_code": "..."
}
-->
```

## ডিবাগিং এবং সমস্যা সমাধান

### সাধারণ সমস্যা

**Quiz অ্যাপ আরম্ভ হয় না**:
- Node.js সংস্করণ পরীক্ষা করুন (v14+ সুপারিশ করা হয়েছে)
- `node_modules` ও `package-lock.json` মুছে পুনরায় `npm install` চালান
- পোর্ট সংঘর্ষ আছে কিনা দেখুন (ডিফল্ট: Vite পোর্ট ৫১৭৩)

**API সার্ভার শুরু হয় না**:
- Node.js সংস্করণ কমপক্ষে (node >=10) নিশ্চিত করুন
- পোর্ট ইতিমধ্যেই ব্যবহৃত হচ্ছে কিনা দেখুন
- সমস্ত নির্ভরতা `npm install` দিয়ে ইনস্টল করা হয়েছে কিনা নিশ্চিত করুন

**ব্রাউজার এক্সটেনশন লোড হচ্ছে না**:
- manifest.json সঠিক ফর্ম্যাটে আছে কিনা পরীক্ষা করুন
- ব্রাউজার কনসোলে ত্রুটি দেখুন
- ব্রাউজার-নির্দিষ্ট এক্সটেনশন ইনস্টল নির্দেশনা অনুসরণ করুন

**Python চ্যাট প্রকল্প সমস্যা**:
- OpenAI প্যাকেজ ইনস্টল আছে কিনা যাচাই করুন: `pip install openai`
- GITHUB_TOKEN পরিবেশ ভেরিয়েবল সেট আছে কিনা নিশ্চিত করুন
- GitHub Models অ্যাক্সেস অনুমতি পরীক্ষা করুন

**Docsify ডকস পরিবেশন করছে না**:
- docsify-cli গ্লোবালি ইনস্টল করুন: `npm install -g docsify-cli`
- রিপোজিটরি রুট থেকে চালান
- `docs/_sidebar.md` ফাইল আছে কিনা চেক করুন

### উন্নয়ন পরিবেশ টিপস

- HTML প্রকল্পের জন্য VS Code এর Live Server এক্সটেনশন ব্যবহার করুন
- ESLint ও Prettier এক্সটেনশন ইনস্টল করুন সুশৃঙ্খল ফরম্যাটিং এর জন্য
- JavaScript ডিবাগিং এর জন্য ব্রাউজার DevTools ব্যবহার করুন
- Vue প্রকল্পের জন্য Vue DevTools ব্রাউজার এক্সটেনশন ইনস্টল করুন

### পারফরম্যান্স বিবেচনা

- অনুবাদকৃত ফাইলের সংখ্যা অনেক (৫০+ ভাষা) তাই পুরো ক্লোন বড় হবে
- শুধুমাত্র বিষয়বস্তু নিয়ে কাজ করলে `git clone --depth 1` ব্যবহার করুন
- ইংরেজি বিষয়বস্তুর জন্য অনুসন্ধানে অনুবাদগুলি বাদ দিন
- প্রথমবার বিল্ড ধীরে হতে পারে (npm install, Vite build)

## সুরক্ষা বিবেচনা

### পরিবেশ ভেরিয়েবলসমূহ

- API কী কখনই রিপোজিটরিতে কমিট করবেন না
- `.env` ফাইল ব্যবহার করুন (যা `.gitignore` তে আছে)
- প্রকল্পের README-তে প্রয়োজনীয় পরিবেশ ভেরিয়েবল ডকুমেন্ট করুন

### Python প্রকল্পসমূহ

- ভার্চুয়াল এনভায়রনমেন্ট ব্যবহার করুন: `python -m venv venv`
- নির্ভরতা হালনাগাদ রাখুন
- GitHub টোকেনের ন্যূনতম প্রয়োজনীয় অনুমতি থাকা উচিত

### GitHub Models অ্যাক্সেস

- GitHub Models এর জন্য Personal Access Tokens (PAT) প্রয়োজন
- টোকেনগুলো পরিবেশ ভেরিয়েবল হিসেবে সংরক্ষণ করুন
- টোকেন বা ক্রেডেনশিয়াল কখনো প্রকাশ করবেন না

## অতিরিক্ত দ্রষ্টব্য

### লক্ষ্য দর্শক

- ওয়েব ডেভেলপমেন্টের সম্পূর্ণ শুরু করার ধাপের শিক্ষার্থীরা
- স্টুডেন্ট এবং স্বশিক্ষার্থীরা
- শ্রেণীকক্ষে কারিকুলাম ব্যবহারে শিক্ষকরা
- বিষয়বস্তু অ্যাক্সেসযোগ্য এবং ধাপে ধাপে দক্ষতা বৃদ্ধির জন্য ডিজাইন করা

### শিক্ষণীয় দর্শন

- প্রকল্পভিত্তিক শেখার পদ্ধতি
- নিয়মিত জ্ঞানের যাচাই (কুইজ)
- হাতে কলমে কোডিং কর্মশালা
- বাস্তব জীবন প্রয়োগ উদাহরণ
- ফ্রেমওয়ার্কের আগে মূল বিষয়গুলিতে ফোকাস

### রিপোজিটরি রক্ষণাবেক্ষণ

- সক্রিয় শিক্ষার্থী ও অবদানকারী সম্প্রদায়
- নির্ভরতা এবং বিষয়বস্তু নিয়মিত আপডেট হয়
- রক্ষণাবেক্ষক দ্বারা ইস্যু ও আলোচনা মনিটার করা হয়
- অনুবাদ আপডেট GitHub Actions দ্বারা স্বয়ংক্রিয়

### সম্পর্কিত রিসোর্স

- [Microsoft Learn modules](https://docs.microsoft.com/learn/)
- [Student Hub resources](https://docs.microsoft.com/learn/student-hub/)
- [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) শিক্ষার্থীদের জন্য সুপারিশকৃত
- অতিরিক্ত কোর্স: Generative AI, Data Science, ML, IoT কারিকুলাম উপলব্ধ

### নির্দিষ্ট প্রকল্প নিয়ে কাজ করা

প্রতিটি প্রকল্পের বিস্তারিত নির্দেশনার জন্য README ফাইলগুলি দেখুন:
- `quiz-app/README.md` - Vue 3 কুইজ অ্যাপ্লিকেশন
- `7-bank-project/README.md` - ব্যাংকিং অ্যাপ্লিকেশন সহ প্রমাণীকরণ
- `5-browser-extension/README.md` - ব্রাউজার এক্সটেনশন ডেভেলপমেন্ট
- `6-space-game/README.md` - ক্যানভাস-বেসড গেম ডেভেলপমেন্ট
- `9-chat-project/README.md` - AI চ্যাট অ্যাসিস্ট্যান্ট প্রকল্প

### মনোরিপো গঠন

এটি ঐতিহ্যবাহী মনোরিপো না হলেও এই রিপোজিটরিতে বহুল স্বতন্ত্র প্রকল্প আছে:
- প্রতিটি পাঠ স্বায়ত্তশাসিত
- প্রকল্পসমূহের নির্ভরতা ভাগাভাগি নেই
- পৃথক প্রকল্পে কাজ করুন অন্যদের প্রভাব ছাড়াই
- সম্পূর্ণ কারিকুলামের অভিজ্ঞতার জন্য সম্পূর্ণ রিপো ক্লোন করুন

---

<!-- CO-OP TRANSLATOR DISCLAIMER START -->
**দ্রষ্টব্য**:  
এই নথিটি [Co-op Translator](https://github.com/Azure/co-op-translator) AI অনুবাদ সেবা ব্যবহার করে অনূদিত হয়েছে। আমরা যথাসাধ্য সঠিকতা বজায় রাখতে চেষ্টা করি, তবে স্বয়ংক্রিয় অনুবাদে ত্রুটি বা অসঙ্গতি থাকতে পারে জেনে রাখুন। মূল নথি তার স্থানীয় ভাষায়ই কর্তৃত্বপূর্ণ উৎস হিসেবে বিবেচিত হওয়া উচিত। সংকটাপন্ন তথ্যের জন্য পেশাদার মানব অনুবাদের পরামর্শ দেওয়া হয়। এই অনুবাদের ব্যবহারের ফলে যে কোনো ভুল ধারণা বা ভুল ব্যাখ্যার দায় আমরা নিতে পারি না।
<!-- CO-OP TRANSLATOR DISCLAIMER END -->