# AGENTS.md

## প্রকল্পের সারসংক্ষেপ

এটি শিক্ষানবীশদের জন্য ওয়েব ডেভেলপমেন্টের মৌলিক বিষয় শেখানোর জন্য একটি শিক্ষামূলক পাঠক্রম রেপোসিটরি। এই পাঠক্রমটি মাইক্রোসফট ক্লাউড অ্যাডভোকেটদের দ্বারা উন্নত একটি ব্যাপক ১২-সপ্তাহের কোর্স, যা জাভাস্ক্রিপ্ট, CSS এবং HTML-এ ২৪টি হাতেকলমে পাঠ নিয়ে গঠিত।

### মূল উপাদানসমূহ

- **শিক্ষামূলক বিষয়বস্তু**: প্রকল্পভিত্তিক মডিউল আকারে সংগঠিত ২৪টি কাঠামোবদ্ধ পাঠ
- **বাস্তব প্রকল্পসমূহ**: টেরারিয়াম, টাইপিং গেম, ব্রাউজার এক্সটেনশন, স্পেস গেম, ব্যাংকিং অ্যাপ, কোড এডিটর, এবং AI চ্যাট সহকারী
- **ইন্টারেক্টিভ কুইজ**: প্রতিটি কুইজে ৩টি প্রশ্নসহ ৪৮টি কুইজ (পাঠের আগে/পরবর্তী মূল্যায়ন)
- **বহুভাষী সমর্থন**: গিটহাব অ্যাকশনের মাধ্যমে ৫০+ ভাষায় স্বয়ংক্রিয় অনুবাদ
- **প্রযুক্তি**: HTML, CSS, জাভাস্ক্রিপ্ট, Vue.js 3, Vite, Node.js, Express, পাইথন (AI প্রকল্পের জন্য)

### স্থাপত্য

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

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

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

### প্রধান রেপোসিটরি সেটআপ

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

### কুইজ অ্যাপ সেটআপ (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 খুলুন অথবা Live Server ব্যবহার করুন
```

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

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

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

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

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

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

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

### সরাসরি উন্নয়ন

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

## পরীক্ষার নির্দেশনা

### কুইজ অ্যাপ পরীক্ষা

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

### ব্যাংক API পরীক্ষা

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

### সাধারণ পরীক্ষার পদ্ধতি

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

### সাবমিশনের পূর্বে যাচাই

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

## কোড স্টাইল গাইডলাইন

### জাভাস্ক্রিপ্ট

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

### HTML/CSS

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

### পাইথন

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

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

- স্পষ্ট হেডিং শ্রেণীবিভাগ
- ভাষা নির্দিষ্ট কোড ব্লক
- অতিরিক্ত রিসোর্সের লিঙ্ক
- `images/` ডিরেক্টরিতে স্ক্রিনশট ও ছবি
- অ্যাক্সেসিবিলিটির জন্য চিত্রের জন্য alt টেক্সট

### ফাইল আয়োজন

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

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

### কুইজ অ্যাপ ডিপ্লয়মেন্ট (Azure Static Web Apps)

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

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

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 serve                 # লোকালহোস্ট:৩০০০ এ সার্ভ করুন
```

### প্রকল্প-নির্দিষ্ট বিল্ড

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

## পুল রিকোয়েস্ট নির্দেশিকা

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

পরিবর্তনের ক্ষেত্র নির্দেশ করে পরিষ্কার, বর্ণনামূলক শিরোনাম ব্যবহার করুন:
- `[Quiz-app] নতুন কুইজ যোগ করুন পাঠ X এর জন্য`
- `[Lesson-3] টেরারিয়াম প্রকল্পে টাইপো সংশোধন`
- `[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 গুলো রক্ষণাবেক্ষক ও কমিউনিটি দ্বারা পর্যালোচনা করা হয়
- শিক্ষামূলক পরিষ্কারতা অগ্রাধিকার পায়
- কোড উদাহরণ সর্বশেষ সেরা অনুশীলন অনুসরণ করে হবে
- অনুবাদ যথার্থতা ও সাংস্কৃতিক প্রাসঙ্গিকতার দিক থেকে পর্যালোচনা করা হয়

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

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

- গিটহাব অ্যাকশনের 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": "..."
}
-->
```

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

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

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

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

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

**পাইথন চ্যাট প্রকল্প সমস্যা**:
- OpenAI প্যাকেজ ইনস্টল আছে কিনা: `pip install openai`
- GITHUB_TOKEN পরিবেশ ভেরিয়েবল সেট আছে কিনা যাচাই করুন
- গিটহাব মডেল অ্যাক্সেস অনুমতি যাচাই করুন

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

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

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

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

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

## নিরাপত্তা বিবেচনা

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

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

### পাইথন প্রকল্পসমূহ

- ভার্চুয়াল এনভায়রনমেন্ট ব্যবহার করুন: `python -m venv venv`
- ডিপেনডেন্সিগুলো আপডেট রাখুন
- গিটহাব টোকেনের আধুনিক এবং সর্বনিম্ন প্রয়োজনীয় অনুমতি দিন

### গিটহাব মডেলস অ্যাক্সেস

- গিটহাব মডেলসের জন্য ব্যক্তিগত অ্যাক্সেস টোকেন (PAT) প্রয়োজন
- টোকেন পরিবেশ ভেরিয়েবল হিসেবে সংরক্ষণ করুন
- টোকেন বা শংসাপত্র কখনো কমিট করবেন না

## অতিরিক্ত নোট

### লক্ষ্য শ্রোতা

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

### শিক্ষামূলক দর্শন

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

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

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

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

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