Skip to content

Update static pages, policies, documentation and contributor guidelines #209

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
trtajim merged 2 commits into from
Aug 28, 2026
Merged

Update static pages, policies, documentation and contributor guidelines #209

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
cb36b4c
Update static pages, policies, documentation and contributor guidelines
trtajim Aug 28, 2026
00d8958
Fix code style and formatting with prettier and eslint
trtajim Aug 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
91 changes: 58 additions & 33 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Contributing to HSCStack

Thanks for your interest in HSCStack! This project is built by and for HSC students in Bangladesh, and we welcome help from fellow developers.
Thanks for your interest in HSCStack! This project is built by and for HSC & SSC students in Bangladesh, and we welcome help from fellow developers.

## Before You Start

Expand All @@ -10,16 +10,21 @@ HSCStack's codebase is **not open for general, unsolicited pull requests**. To c
2. Once your application is reviewed and accepted, you'll be onboarded to the codebase.
3. After that, you're free to open issues, pick up tasks, and submit PRs following the workflow below.

If you're not yet a core developer but found a bug or have a suggestion, please [open a GitHub Issue](https://github.com/trtajim/hscstack/issues) instead — no membership required for that.
If you're not yet a core developer but found a bug or have a suggestion, please [open a GitHub Issue](https://github.com/hscstack/platform/issues) instead — no membership required for that.

## Tech Stack

| Layer | Technology |
|--------------|------------------------|
| Backend | Laravel (PHP) |
| Frontend | Vue.js via Inertia.js |
| Storage | Public file storage |
| Admin Panel | Built-in Laravel admin |
| Layer | Technology |
| --------------- | ------------------------------------ |
| **Backend** | Laravel 12 (PHP) |
| **Frontend** | Vue 3 + TypeScript via Inertia.js v3 |
| **Styling** | Tailwind CSS v4 |
| **Realtime** | Pusher Channels + Laravel Echo |
| **Storage** | AWS S3 / Cloudflare R2 |
| **Auth** | Google OAuth 2.0 (Laravel Socialite) |
| **Analytics** | PostHog |
| **Permissions** | Spatie Laravel Permission |
| **PWA** | vite-plugin-pwa |

## Development Setup

Expand All @@ -46,21 +51,30 @@ php artisan serve
pnpm dev
```

### Additional Setup (Optional)

- **Google OAuth:** Configure `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, and `GOOGLE_REDIRECT_URI` in `.env` for authentication.
- **Pusher:** Configure `PUSHER_APP_ID`, `PUSHER_APP_KEY`, `PUSHER_APP_SECRET` in `.env` for live chat.
- **S3/R2 Storage:** Configure `AWS_*` or `CLOUDFLARE_*` keys for file uploads.
- **PostHog:** Configure `POSTHOG_*` keys for analytics.
- **YouTube Data API:** Configure `YOUTUBE_API_KEY` for playlist imports.
- **Short.io:** Configure `SHORT_IO_*` keys for URL shortening.

## Workflow

1. Create a new branch off `main`:
```bash
git checkout -b feature/your-feature-name
```
```bash
git checkout -b feature/your-feature-name
```
2. Make your changes, following the code style guidelines below.
3. Commit with a clear, descriptive message:
```bash
git commit -m "Add: your feature"
```
```bash
git commit -m "Add: your feature"
```
4. Push your branch and open a Pull Request:
```bash
git push origin feature/your-feature-name
```
```bash
git push origin feature/your-feature-name
```
5. Fill out the PR description explaining what changed and why, and link any related issue.

### Branch naming
Expand Down Expand Up @@ -89,45 +103,56 @@ php artisan test
```

General guidelines:

- Follow existing Laravel conventions (FormRequests for validation, resource controllers, etc.).
- Keep Vue components under `resources/js/Pages` and `resources/js/Components` organized and reusable.
- Keep Vue components under `resources/js/pages/` and `resources/js/components/` organized and reusable.
- Avoid passing non-database fields into mass assignment (`create()`/`update()`); validate and filter explicitly.
- Keep PRs focused — one feature or fix per PR is easier to review.
- Use TypeScript types defined in `resources/js/types/` for all component props and API responses.
- Follow the existing cache invalidation pattern using Observers when adding new cacheable models.

## Project Structure

```
hscstack/
platform/
├── app/
│ ├── Models/ # Subject, Node, Resource models
│ ├── Http/Controllers/ # Web + Admin controllers
│ └── ...
│ ├── Models/ # Eloquent models (User, Subject, Node, Resource, Blog, etc.)
│ ├── Http/Controllers/ # Web + Admin + API controllers
│ ├── Mail/ # Mailable classes (Welcome, Notifications, Broadcasts)
│ ├── Observers/ # Cache invalidation observers
│ ├── Services/ # Business logic services
│ └── Console/Commands/ # Artisan CLI commands
├── resources/
│ ├── js/
│ │ ├── Pages/ # Inertia Vue pages
│ │ └── Components/ # Reusable Vue components
│ └── views/ # Blade layouts
│ │ ├── pages/ # Inertia Vue pages
│ │ ├── components/ # Reusable Vue components
│ │ ├── layouts/ # App layouts
│ │ └── types/ # TypeScript type definitions
│ └── views/ # Blade templates
├── routes/
│ ├── web.php # Public routes
│ └── admin.php # Admin routes
├── public/storage/ # Uploaded files
├── .env.example
│ ├── web.php # Public & auth routes
│ ├── admin.php # Admin panel routes
│ └── api.php # API routes (chat, auth, short URLs)
├── database/migrations/ # Database schema migrations
├── config/ # App configuration
├── docs/ # Developer documentation
└── README.md
```

## Content Contributions (Non-Code)

If you want to contribute academic resources (notes, PDFs, questions, etc.) rather than code, you don't need to touch this repository at all. Instead:
If you want to contribute academic resources (notes, PDFs, questions, images, videos) rather than code, you don't need to touch this repository at all. Instead:

1. Become a member at [hscstack.site/join](https://hscstack.site/join)
2. Log in to the platform and upload your resource under the relevant subject and chapter.
3. Your submission goes live after a quick admin review.
2. Log in with Google and navigate to the relevant subject and chapter.
3. Upload your resource with a clear title and content.
4. Your submission goes live after admin review.

Please only upload content you created or have permission to share, and avoid copyrighted textbooks or board materials.

## Reporting Bugs & Requesting Features

- Use [GitHub Issues](https://github.com/trtajim/hscstack/issues) for bugs and feature requests.
- Use [GitHub Issues](https://github.com/hscstack/platform/issues) for bugs and feature requests.
- Include steps to reproduce, expected vs. actual behavior, and screenshots if relevant (for UI bugs).

## Questions?
Expand Down
126 changes: 71 additions & 55 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,39 +5,49 @@

> A curated resource platform for HSC & SSC students of Bangladesh — built by members, for everyone.

HSCStack is a lightweight, structured platform where verified members share academic resources — practicals, notes, PDFs, videos, and questions — organized by subject and chapter, so every SSC & HSC student can find what they need in one place.
HSCStack is a structured platform where verified members share academic resources — notes, questions, PDFs, images, and videos — organized by subject and chapter, so every SSC & HSC student can find what they need in one place. On top of that, we've got a real-time community chat, an educational blog, study progress tracking, and an AI learning assistant — all completely free and ad-free.

---

## 🌟 What is HSCStack?

HSCStack is built for students preparing for the **Higher Secondary Certificate (HSC)** & **Secoondary School Certificate (SSC)** exams in Bangladesh. It brings together a trusted library of student-made resources, organized neatly by subject and chapter — no more digging through WhatsApp groups or random Facebook posts.
HSCStack is built for students preparing for the **Higher Secondary Certificate (HSC)** and **Secondary School Certificate (SSC)** exams in Bangladesh. It brings together a trusted library of student-made resources, organized neatly by subject and chapter — no more digging through WhatsApp groups or random Facebook posts.

You can switch between HSC and SSC curricula seamlessly. Each subject has nested chapters and topics, so you can drill down to exactly what you're looking for. Resources are uploaded by verified members to keep quality high, and the community votes on the best folders to surface them to the top.

Browsing is open to everyone. But to **contribute**, you need to be an HSCStack member first — keeping the content quality high and the community trustworthy.

---

## ✨ Features

- 📂 **Subject Archive** — Resources organized under subjects with visual themes and icons.
- 🗂️ **Chapter-based Structure** — Each subject has nested chapters (nodes) so you can find exactly what you need.
- 📄 **Multiple Resource Types** — Notes, PDFs, images, videos, and exam questions — all in one place.
- 🔒 **Members-Only Uploads** — Only verified HSCStack members can contribute content.
- 🛠️ **Admin Panel** — Full control over subjects, chapters, and resources via a clean admin area.
- ☁️ **File Upload Support** — Resources are stored and served from public storage.
- 🆓 **Free to Browse** — No account needed to read or download resources.
- 📝 **Educational Blog** — Read study tips, announcements, learning guides, and educational articles.
- 📂 **Dual Curriculum** — Switch between HSC and SSC. Subjects organized with custom icons, color-coded badges, and sort order.
- 🗂️ **Deep Folder Structure** — Infinite nesting: subject → chapter → topic → sub-topic. Breadcrumb navigation with caching for speed.
- 📄 **5 Resource Types** — Notes, questions, PDFs, images, and videos. Direct uploads to S3/R2 or external links.
- ⬆️ **Community Voting** — Upvote/downvote folders. Best content rises to the top.
- ✅ **Progress Tracking** — Mark resources as "Completed." See completion counts and who's been studying.
- 🎥 **Custom YouTube Player** — Watch classes without YouTube ads or distracting recommendations. Custom controls with variable speed (0.75x–2x), 5-second skip, and fullscreen.
- 💬 **Live Chat** — Real-time global chat with message replies, @mentions, emoji reactions, and a smart profanity filter. Community reporting with auto-ban for repeat offenders.
- 👤 **Public Profiles** — Vanity URLs (`/u/{username}`) with bio, institution, avatar, social links, and a unified activity stream.
- ❤️ **Peer Appreciations** — Appreciate members with milestone email notifications.
- ✍️ **Blog** — Full CMS with slug URLs, featured images, SEO tags, love reactions, and threaded comments.
- 🤖 **AI Assistant** — Dedicated interface organized by STEM subjects and chapters.
- 🔗 **URL Shortener** — Floating share bar on every page, powered by Short.io.
- 📱 **PWA** — Install it like an app. Works offline with a service worker.
- 🔔 **Notice Banner** — Site-wide announcements with images and CTA buttons.
- 🔒 **Google Sign-in** — One-click OAuth 2.0 authentication.

---

## 📚 Resource Types

| Type | Description |
| ---------- | ------------------------------------------------- |
| **Notes** | Handwritten or typed notes by fellow students |
| **PDFs** | Formatted documents, guides, and reference sheets |
| **Images** | Diagrams, charts, and visual study aids |
| **Videos** | Classes from Youtube |
| Type | Description |
| ------------- | ------------------------------------------------- |
| **Notes** | Handwritten or typed notes by fellow students |
| **Questions** | Exam questions and practice problems |
| **PDFs** | Formatted documents, guides, and reference sheets |
| **Images** | Diagrams, charts, and visual study aids |
| **Videos** | Ad-free YouTube classes via custom native player |

---

Expand All @@ -46,76 +56,79 @@ Browsing is open to everyone. But to **contribute**, you need to be an HSCStack
### For Students (Browsing)

1. Visit [HSCStack][website] — no account needed.
2. Pick your subject and chapter.
2. Pick your curriculum (HSC or SSC), then select a subject and chapter.
3. Browse, read, or download any resource freely.

### For Members (Contributing)

Only HSCStack members can upload resources. To become a member:

1. Join at 👉 **[hscstack.site/join][join]**
2. Once accepted, log in and go to the relevant subject and chapter.
3. Upload your resource — add a title, type, and short description.
4. Your contribution goes live after a quick admin review.
2. Once accepted, sign in with Google and go to the relevant subject and chapter.
3. Upload your resource — add a title, type, and content.
4. Your contribution goes live after admin review.

> **Why membership?** We keep uploads member-only to maintain quality and ensure content is relevant, accurate, and trustworthy for all HSC students.
> **Why membership?** We keep uploads member-only to maintain quality and ensure content is relevant, accurate, and trustworthy for all students.

---

## 🛠️ Tech Stack

| Layer | Technology |
| --------------- | --------------------------- |
| **Backend** | Laravel (PHP) |
| **Frontend** | Vue.js via Inertia.js |
| **Storage** | Public file storage |
| **Admin Panel** | Built-in Laravel admin area |
| Layer | Technology |
| --------------- | ------------------------------------ |
| **Backend** | Laravel 12 (PHP) |
| **Frontend** | Vue 3 + TypeScript via Inertia.js v3 |
| **Styling** | Tailwind CSS v4 |
| **Realtime** | Pusher Channels + Laravel Echo |
| **Storage** | AWS S3 / Cloudflare R2 |
| **Auth** | Google OAuth 2.0 (Laravel Socialite) |
| **Analytics** | PostHog |
| **Permissions** | Spatie Laravel Permission |
| **PWA** | vite-plugin-pwa |
| **Backup** | Google Drive API (automated) |

---

## 📖 Developer Documentation

Additional documentation for developers:

- [Google Drive Backup](docs/google-drive-backup.md)
- [Google Drive Backup Setup](docs/google-drive-backup.md)
- [Storage Cleanup Command](docs/storage-cleanup.md)

---

## 🤝 Contributing to the Codebase

HSCStack is not open for general pull requests. To contribute code, you must be a **core developer** on the team.

To apply, join via 👉 **[hscstack.site/join][join]** — once your application is reviewed and accepted, we'll onboard you to the codebase.
## 🤝 Contributing

Once you're a core developer:
HSCStack welcomes contributions from core developers. See [CONTRIBUTING.md](CONTRIBUTING.md) for the development setup, workflow, and code style guidelines.

1. Clone the repository
2. Create a new branch: `git checkout -b feature/your-feature-name`
3. Commit your changes: `git commit -m "Add: your feature"`
4. Push to your branch: `git push origin feature/your-feature-name`
5. Open a Pull Request for review
Not a developer? You can still contribute academic resources (notes, PDFs, questions) by joining at **[hscstack.site/join][join]**.

---

## 📁 Project Structure

```
hscstack/
platform/
├── app/
│ ├── Models/ # Subject, Node, Resource models
│ ├── Http/Controllers/ # Web + Admin controllers
│ └── ...
│ ├── Models/ # Eloquent models (User, Subject, Node, Resource, Blog, etc.)
│ ├── Http/Controllers/ # Web + Admin + API controllers
│ ├── Mail/ # Mailable classes
│ ├── Observers/ # Cache invalidation observers
│ ├── Services/ # Business logic services
│ └── Console/Commands/ # Artisan CLI commands (backup, sitemap, cleanup)
├── resources/
│ ├── js/
│ │ ├── Pages/ # Inertia Vue pages
│ │ └── Components/ # Reusable Vue components
│ └── views/ # Blade layouts
│ │ ├── pages/ # Inertia Vue pages
│ │ ├── components/ # Reusable Vue components
│ │ ├── layouts/ # App layouts
│ │ └── types/ # TypeScript type definitions
│ └── views/ # Blade templates
├── routes/
│ ├── web.php # Public routes
│ └── admin.php # Admin routes
├── public/storage/ # Uploaded files
├── .env.example
└── README.md
│ ├── web.php # Public & auth routes
│ ├── admin.php # Admin panel routes
│ └── api.php # API routes (chat, auth, short URLs)
├── database/migrations/ # Database schema
├── config/ # App configuration
└── docs/ # Developer docs
```

---
Expand All @@ -125,12 +138,14 @@ hscstack/
HSCStack's value comes from the quality of what's shared. Please follow these rules:

- ✅ Only upload content **you created** or have permission to share.
- ✅ Keep everything **relevant to the HSC Bangladesh curriculum**.
- ✅ Keep everything **relevant to the HSC/SSC Bangladesh curriculum**.
- ✅ Add **clear titles and descriptions** so others can find your resource.
- ✅ Be respectful in live chat and comments.
- ❌ Do not upload copyrighted textbooks or board materials without permission.
- ❌ No spam, duplicate, or off-topic content.
- ❌ No profanity, harassment, or hate speech in chat.

Breaking these rules may result in content removal or membership revocation.
Breaking these rules may result in content removal, chat bans, or account suspension.

---

Expand All @@ -140,6 +155,7 @@ Have a question, found a bug, or want to get involved?

- 📧 Email: `com.tajim@gmail.com`
- 🐛 Issues: [Open a GitHub Issue](../../issues)
- ❤️ Support: [hscstack.site/support](https://hscstack.site/support)

---

Expand Down
Loading