https://github.com/alibekn6/flashcards-master
A flashcard study app organized by topics. Users answer questions, flip cards, and track their progress as they learn, for nfactorial 2025
https://github.com/alibekn6/flashcards-master
jwt-authentication nestjs-backend postgresql react
Last synced: 2 months ago
JSON representation
A flashcard study app organized by topics. Users answer questions, flip cards, and track their progress as they learn, for nfactorial 2025
- Host: GitHub
- URL: https://github.com/alibekn6/flashcards-master
- Owner: alibekn6
- Created: 2025-04-24T12:16:00.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-05-05T18:43:17.000Z (about 1 year ago)
- Last Synced: 2025-09-06T10:35:21.156Z (10 months ago)
- Topics: jwt-authentication, nestjs-backend, postgresql, react
- Language: TypeScript
- Homepage: https://flashcards-master.vercel.app
- Size: 356 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Flashcards Master – core api / client
Это серверная и клиентская часть проекта **Flashcards Master** – приложения для интерактивного обучения с использованием карточек. Сервис позволяет пользователям регистрироваться, входить в систему, создавать карточки, отслеживать прогресс и использовать внешние источники, для автоматической генерации карточек.
- ⚠️ Fixed (костыль) запустил питон скрипт который keeps server awake, теперь не придется ждать по минутам 🥳
- **⚠️WARNING⚠️** – ! я использовал бесплатные возможности render и gemini, возможно скорость приложение будет чуть низким (be patient or text me)
[t.me/internalpointer](https://t.me/internalpointer)
## Стек
core-api
- **NestJS** – фреймворк Node.js для серверной части
- **TypeORM** – ORM для PostgreSQL
- **PostgreSQL** – основная база данных
- **JWT (JSON Web Token)** – авторизация и аутентификация
- **Swagger (OpenAPI)** – документация API
- **Gemini** – Google Gemini для генерации карточек
- **Jest** – модульное тестирование
- **ESLint + Prettier + Husky + lint-staged** – обеспечение качества кода
client
- **React** – фреймворк клиентской части
- **React router dom** – для удобной навигаций
- **tailwindcss** - для стилей
---
## 🛠 Установка и запуск сервера
```bash
**server side**
# 1. Клонировать репозиторий
git clone https://github.com/alibekn6/flashcards-master
cd flashcards-api
# 2. Установить зависимости
npm install
# 3. Создать .env файл
.env
# отредактируйте .env и укажите свои значения (DB_USER, DB_PASSWORD, JWT_SECRET, GEMINI_API_KEY and so on)
# 4. Запустить PostgreSQL
pgadmin / psql на юникс системах через терминал
- psql -U {username} -d
- CREATE DATABASE flashcards, \q
- psql -U {username} -d flashcards
или сделать тоже самое на графическом интерфейсе
# 5. Запустить сервер
npm run start:dev
**client side**
# 1. перейти в
cd flashcards-client
# 2. Установить зависимости
npm install
# 3. Создать .env файл
.env
# отредактируйте .env и укажите свои значения
# 4. указать правильный путь к API
VITE_API_URL=http://localhost:3000/api
# 5. Запустить сервер
npm run dev
вуаля у вас есть локоальная версия моего проекта, enjoy
# auth login (if you dont want to create account and want to see already created fodlers and flashcards)
email: alibek@kbtu.kz
password: pass
```
**Описание процесса проектирования и разработки**
*Архитектура бэкенда (Nest, Postgres)*
- Выбрал модульную структуру с разделением на контроллеры, сервисы и репозитории, что упростило масштабирование и поддержку.
- Безопасность реализована через JWT-аутентификацию и защищённые маршруты.
- Для работы с базой данных использовался TypeORM, позволяющий легко управлять миграциями и связями между сущностями.
- Валидация запросов через Validation Pipes
*Frontend*
- Использованы функциональные компоненты с хуками.
- Реализация роутинга через React Router.
- Контекстное хранилище (Context API) используется для управления состоянием.
- Созданы кастомные хуки для взаимодействия с API.
- Применены css module для изоляции стилей и обеспечения адаптивности
**Уникальные подходы и методологии**
*Модульность и чистая архитектура:*
- Жесткое разграничение логики между слоями: контроллеры, сервисы, репозитории
- Это обеспечивает высокую тестируемость и простоту добавления новых фич
*Интеграция искусственного интеллекта (Google Gemini):*
- Генерация карточек осуществляется автоматически на основе заранее продуманных промптов
- Это снижает порог входа для пользователей и ускоряет наполнение контента
*Система тестирования*
- Различные форматы вопросов
- Подсчет правильных/неправильных ответов
**Компромиссы в процессе разработки**
*Структура базы данных:*
- Связи между карточками и папками реализованы упрощённо
- Это снижает гибкость, но ускоряет разработку на раннем этапе
*Интеграция ИИ*
- API Gemini вызывается напрямую, без очередей или фоновых задач.
- Это упрощает реализацию, но может привести к проблемам при росте нагрузки.
**Известные проблемы**
*Генерация карточек:*
- Требуется ручное обновление страницы для отображения новых карточек.
- Временное решение — ре-рендер.
*Адаптивность:*
- Некоторые элементы не идеально масштабируются на мобильных устройствах.
*Режим тестирования:*
- Простейший подсчет очков то есть только на клиенте
- Отсутствует сохранение прогресса между сессиями
**почему выбрал этот технический стэк**
*core api*
- NestJS выбран за модульность, строгую типизацию (TypeScript), легкость масштабировать, добалять и переиспользовать сервисы
- PostgreSQL — надёжная, производительная СУБД
- TypeORM упрощает работу с базой, миграции и взаимодействие с сущностями
- это отличный баланс между производительностью и поддерживаемостью
- Идеально подходит для архитектуры среднего масштаба
- Прост в расширении и внедрении новых фич
*client*
- React обеспечивает быструю разработку и переиспользуемость компонентов
- React Router упрощает навигацию
- Context API достаточен на текущем этапе, без необходимости внедрения сложного хранилища
- CSS Modules позволяют делать интерфейс адаптивным и поддерживаемым