🏫 ПГКНМА Дигитална Платформа - Фронтенд

Backend (Django REST API + admin): Krumqnkata/pgknma-blog-backend

📝 Общ преглед

Това е фронтенд приложението на дигиталната платформа на Професионална гимназия по компютърно моделиране и компютърни анализи "Проф. Минко Балкански" (ПГКНМА). Проектът е изграден с цел да предостави на учениците и учителите модерна, бърза и интерактивна среда за достъп до училищна информация и забавления.

Приложението е разработено с React 18, TypeScript и Vite, като се фокусира върху отлична производителност, достъпност и модерен дизайн.

📚 Техническа документация

Подробната и поддържана документация за frontend-а е в docs/README.md:

• Архитектура, routing и компоненти
• State, JWT и API интеграция
• UI, accessibility, SEO и PWA
• Разработка, тестове и build

Backend/API/deployment документацията е в отделния backend repository, в неговата папка docs/.

🛠️ Технологичен стек (Deep Dive)

Ядро (Core)

• React 18: Компонентно-базирана архитектура с Hooks.
• TypeScript: Типова проверка за по-стабилен код; виж docs/STATE_AND_API.md за текущите настройки и ограничения.
• Vite: Ултра бърз инструмент за разработка и компилация.

Потребителски интерфейс (UI/UX)

• Tailwind CSS: Системен дизайн чрез utility класове.
• Shadcn UI: Премиум компоненти (базирани на Radix UI).
• Lucide React: Библиотека с векторни икони.
• Tailwind animations & tsParticles: За плавни преходи, scroll ефекти и интерактивни частици.
• Next Themes: Автоматична синхронизация на Dark/Light режим.

Управление на данни

• TanStack Query (React Query) v5: Мощно управление на състоянията на сървъра (кеширане, рефетчване).
• Context API: За лека глобална държава (auth, settings).
• React Hook Form & Zod: За валидация на форми и схеми на данни.

📂 Изчерпателна структура на проекта

├── public/                     # Статични ресурси
│   ├── Landscape/              # Галерия с изображения на училищния двор
│   ├── bell.pdf                # График на учебните часове
│   ├── program.csv             # Сурови данни за учебната програма
│   ├── front-page-loop.webm    # Видео фон за началната страница
│   ├── favicon.ico             # Икона на сайта
│   └── robots.txt              # Инструкции за търсачки
├── src/
│   ├── components/             # React компоненти (Градивните елементи)
│   │   ├── ui/                 # Базови Shadcn компоненти (40+ компонента)
│   │   │   ├── button.tsx, input.tsx, card.tsx, dialog.tsx...
│   │   │   ├── chart.tsx       # Визуализация на статистически данни
│   │   │   ├── sidebar.tsx     # Навигационен панел (мобилен/десктоп)
│   │   │   └── carousel.tsx    # Слайдер за изображения
│   │   ├── AccountSettings.tsx # Настройки на потребителския профил
│   │   ├── BellSongForm.tsx    # Форма за предложения за музика
│   │   ├── Comments.tsx        # Система за коментари под новините
│   │   ├── CustomCursor.tsx    # Стилизиран персонализиран курсор
│   │   ├── Header.tsx          # Главна навигация и лого
│   │   ├── Footer.tsx          # Информационен блок в края на страницата
│   │   ├── Hero.tsx            # Първата визуална секция на началната страница
│   │   ├── NewsGrid.tsx        # Сетка за визуализация на новини
│   │   ├── PollStatistics.tsx  # Визуализация на резултатите от анкети
│   │   ├── ProtectedRoute.tsx  # Компонент за ограничаване на достъпа
│   │   └── SearchDialog.tsx    # Търсачка в реално време
│   ├── contexts/               # Управление на състоянието (Providers)
│   │   ├── AuthContext.tsx     # Автентикация, JWT сесии и потребителски роли
│   │   ├── SettingsContext.tsx # Динамични настройки и Feature Flags
│   │   └── GlobalStateContext.tsx # Глобални състояния на интерфейса
│   ├── hooks/                  # Персонализирани Hooks
│   │   ├── use-disable-inspect.ts # Защита срещу F12 и десен бутон
│   │   ├── use-mobile.tsx      # Детекция на типа устройство
│   │   └── use-toast.ts        # Система за изскачащи известия
│   ├── lib/                    # Логика и комуникация (SDK)
│   │   ├── api.tsx             # Всички API заявки (новини, анкети, статус)
│   │   ├── api_auth.tsx        # Логика за логин, регистрация и профил
│   │   └── utils.ts            # Помощни функции за Tailwind и Shadcn
│   ├── pages/                  # Маршрути (Routes)
│   │   ├── Index.tsx           # Начална страница (Dashboard)
│   │   ├── News.tsx            # Пълен списък с новини и филтри
│   │   ├── Post.tsx            # Детайлен изглед на единична новина
│   │   ├── SchoolCalendar.tsx  # Календар със събития (20k+ линии логика)
│   │   ├── TVScreen.tsx        # Дигитален борд за училищни екрани
│   │   ├── WeeklyPoll.tsx      # Страница за гласуване в анкети
│   │   ├── MemeOfTheWeek.tsx   # Платформа за училищни мемета
│   │   ├── BellSuggest.tsx     # Гласуване за музикален фон
│   │   ├── MyProfilePage.tsx   # Личен панел на ученика
│   │   ├── MaintenancePage.tsx # Страница при техническа профилактика
│   │   └── ...                 # Правни страници (Privacy, Terms)
│   ├── styles/                 # CSS конфигурации
│   │   ├── index.css           # Глобални Tailwind стилове
│   │   └── atom-one-dark.css   # Тема за Code Highlighting
│   ├── App.tsx                 # Централен рутер и конфигурация
│   └── main.tsx                # Стартова точка (DOM Rendering)
├── .env.example                # Конфигурационен шаблон
├── tailwind.config.ts          # Дефиниции на теми, цветове и анимации
└── package.json                # Пълен списък със зависимости (deps)

🚀 Детайлни функционалности

🎨 Интерфейс и Потребителско изживяване

• Адаптивен дизайн (Mobile First): Сайтът изглежда перфектно на смартфони, таблети и компютри.
• Тъмна и Светла тема: Автоматично превключване спрямо настройките на операционната система.
• Интерактивни елементи: Използване на частици (tsparticles), паралакс ефекти и плавни преходи между страниците.

📰 Динамично съдържание

• Markdown Rendering: Новините поддържат заглавия, списъци, таблици и код, което позволява на учителите да публикуват богато съдържание.
• Коментари в реално време: Учениците могат да дискутират под всяка новина.

🗳️ Ангажираност на учениците

• Седмични Анкети: Модул с графики (Recharts), показващи общественото мнение.
• Предложения за Звънец: Интеграция с YouTube/Spotify линкове за предложения на музика.

🏢 Училищна администрация (Backend Sync)

• Feature Flags: Дистанционно включване/изключване на модули (например изключване на меметата по време на изпити).
• Maintenance Mode: Възможност за спиране на сайта при профилактика директно от административния панел.

🔧 Технически инструкции

Инсталиране на проекта

1. Клониране:

   git clone https://github.com/Krumqnkata/PGKNMA-Blog.git

2. Зависимости: Препоръчително е използването на bun за по-бърза инсталация:

   bun install
   # или
   npm install

3. Конфигурация:

   cp .env.example .env
   # Отворете .env и задайте VITE_API_BASE_URL

   .env не се качва в git. Всичко с VITE_ влиза в browser bundle-а, затова там никога не слагай пароли или частни ключове.

Команди за разработка

Същите проверки (typecheck, lint, test, build) се пускат автоматично в GitHub Actions при всеки push и pull request.

🔒 Сигурност

Проектът включва няколко нива на защита:

• Cloudflare Turnstile: Защита срещу автоматизирани атаки (spam) във формите.
• JWT Authentication: Сигурно управление на сесиите чрез токени.
• Content Sanitization: Предотвратяване на XSS атаки при рендване на Markdown и коментари.

Ако откриеш уязвимост, не отваряй публичен issue — виж SECURITY.md.

👥 Автори

• Krumqnkata
• ythef0
• lkbonev72

Проектът е създаден за ПГКНМА „Проф. Минко Балкански“ с цел иновация и модернизация на училищния живот.

📄 Лиценз

Кодът е © 2025–2026 Krumqnkata, ythef0 и lkbonev72 и е лицензиран под GNU AGPL v3.0 или по-нова версия. Ако го ползваш или пуснеш като сайт, трябва да запазиш авторството и да публикуваш промените си под същия лиценз.

Името, логата, снимките, видеата и документите на ПГКНМА са собственост на училището и не са част от лиценза. Подробности: NOTICE.md.