https://github.com/lcaohoanq/bit-learning-fe
Bit Learning - Online Coding Learning System Connecting Instructors and Learners
https://github.com/lcaohoanq/bit-learning-fe
ansible cicd docker github-actions monorepo nginx react shadcn-ui typescript
Last synced: 3 months ago
JSON representation
Bit Learning - Online Coding Learning System Connecting Instructors and Learners
- Host: GitHub
- URL: https://github.com/lcaohoanq/bit-learning-fe
- Owner: lcaohoanq
- Created: 2025-10-18T16:26:35.000Z (9 months ago)
- Default Branch: develop
- Last Pushed: 2026-04-24T17:20:18.000Z (3 months ago)
- Last Synced: 2026-04-24T18:28:45.618Z (3 months ago)
- Topics: ansible, cicd, docker, github-actions, monorepo, nginx, react, shadcn-ui, typescript
- Language: TypeScript
- Homepage: https://bit-learning.lch.id.vn
- Size: 81.5 MB
- Stars: 4
- Watchers: 0
- Forks: 0
- Open Issues: 14
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Bit Learning — Frontend
> Monorepo frontend for the **Bit Learning** educational platform, built with React 19, TypeScript, and Vite. Managed by [Turborepo](https://turbo.build/) and [pnpm](https://pnpm.io/) workspaces.
---
## System Architecture
```
┌─────────────────────────────────────────────────────────────────────┐
│ Turborepo Pipeline │
│ (build · dev · lint · check-types) │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────┐ ┌──────────────────────┐ │
│ │ apps/web │ │ apps/admin │ │
│ │ (Student Platform) │ │ (Admin Dashboard) │ │
│ │ :5173 │ │ :8386 │ │
│ │ │ │ │ │
│ │ React 19 + Vite │ │ React 19 + Vite │ │
│ │ TanStack Router │ │ TanStack Router │ │
│ │ TanStack Query │ │ TanStack Query │ │
│ │ Redux Toolkit │ │ Zustand │ │
│ │ i18next │ │ Clerk Auth │ │
│ │ Vitest │ │ Recharts │ │
│ └──────────┬───────────┘ └──────────┬───────────┘ │
│ │ │ │
│ └───────────┬───────────────────┘ │
│ │ │
│ ┌──────────────────────┴──────────────────────┐ │
│ │ packages/ui │ │
│ │ (Shared Component Library) │ │
│ │ │ │
│ │ Radix UI · React Aria · DaisyUI │ │
│ │ Tailwind CSS 4 · Embla Carousel │ │
│ │ Lucide Icons · MapLibre GL │ │
│ │ 60+ reusable components │ │
│ └──────────────────────┬──────────────────────┘ │
│ │ │
│ ┌──────────────────────┴──────────────────────┐ │
│ │ packages/lib │ │
│ │ (Shared Business Logic) │ │
│ │ │ │
│ │ API SDK (Axios) · Zod Validation │ │
│ │ Shared Constants · Utilities │ │
│ │ Type-safe API clients per domain │ │
│ └─────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────┐ │
│ │ packages/typescript-config │ │
│ │ (Shared TSConfig presets) │ │
│ │ base · react-library · nextjs │ │
│ └─────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌───────────────────────┐
│ Backend API │
│ REST + WebSocket │
└───────────────────────┘
```
## Monorepo Structure
```
bit-learning-fe/
├── apps/
│ ├── web/ # Student-facing platform
│ └── admin/ # Admin dashboard
├── packages/
│ ├── ui/ # Shared UI component library
│ ├── lib/ # Shared API SDK, types, validation
│ └── typescript-config/ # Shared TypeScript configurations
├── infra/ # Ansible deployment playbooks
├── turbo.json # Turborepo pipeline config
├── pnpm-workspace.yaml # pnpm workspace definition
├── biome.json # Linter & formatter (Biome)
├── lefthook.yml # Git hooks (pre-commit formatting)
├── Makefile # Docker orchestration shortcuts
├── Jenkinsfile # Jenkins CI/CD pipeline
├── docker-compose-local-dev-latest.yml
└── docker-compose-local-prod-latest.yml
```
## Applications
### `apps/web` — Student Platform
The main learning platform where students interact with courses, exams, quizzes, and more.
| Concern | Stack |
|---|---|
| Framework | React 19 + Vite |
| Routing | TanStack Router (file-based, auto code-splitting) |
| Server State | TanStack Query |
| Client State | Redux Toolkit + Redux Persist |
| Forms | React Hook Form + Zod |
| Styling | Tailwind CSS 4 (PostCSS) |
| i18n | i18next + browser language detection |
| Testing | Vitest + Testing Library + Playwright |
| Code Editor | Monaco Editor |
| Charts | ECharts, Recharts |
| PDF | react-pdf-viewer |
| Realtime | STOMP.js over WebSocket |
Feature modules: `auth` · `course` · `lecture` · `exam` · `quiz` · `question` · `code-practice` · `chat-ai` · `contest` · `forum` · `game` · `mindmap` · `slides` · `dashboard` · `mentor-dashboard` · `order` · `notification` · `onboarding` · `matrix`
### `apps/admin` — Admin Dashboard
Back-office dashboard for managing platform content, users, and system configuration.
| Concern | Stack |
|---|---|
| Framework | React 19 + Vite |
| Routing | TanStack Router (file-based, auto code-splitting) |
| Server State | TanStack Query |
| Client State | Zustand |
| Auth | Clerk |
| Forms | React Hook Form + Zod |
| Styling | Tailwind CSS 4 (Vite plugin) |
| Charts | Recharts |
| Rich Text | React Quill |
| PDF | react-pdf-viewer |
Feature modules: `auth` · `courses` · `curriculum` · `contests` · `games` · `mindmaps` · `posts` · `questions` · `users` · `settings` · `system-prompt` · `templates` · `dashboard`
---
## Shared Packages
### `packages/ui` — Component Library
60+ reusable UI components built on top of Radix UI and React Aria, styled with Tailwind CSS 4 and DaisyUI.
Exports via package `@workspace/ui`:
```ts
import Button from "@workspace/ui/components/Button";
import { cn } from "@workspace/ui/lib/utils";
import useMediaQuery from "@workspace/ui/hooks/useMediaQuery";
```
Key components: `Button` · `DataTable` · `Dialog` · `Form` · `Select` · `Calendar` · `DatePicker` · `Tabs` · `Popover` · `Tooltip` · `Sidebar` · `EmblaCarousel` · `Map` · `Uploader` · `Searchfield` · `ScrollArea` · `Skeleton` · `Spinner` · and more.
### `packages/lib` — Business Logic & API SDK
Shared API clients, types, and validation schemas consumed by both apps.
Exports via package `@workspace/lib`:
```ts
import { authApi } from "@workspace/lib/api/sdk/auth.api";
import { courseSchema } from "@workspace/lib/validation";
```
API SDK domains: `auth` · `chapter` · `exam` · `lesson` · `matrix` · `question` · `subject` · `syllabus` · `example`
Each domain provides a typed API client (`.api.ts`) and its corresponding TypeScript types (`.type.ts`).
### `packages/typescript-config` — TSConfig Presets
Shared TypeScript configuration presets: `base`, `react-library`, `nextjs`.
---
## Getting Started
### Prerequisites
- **Node.js** ≥ 20
- **pnpm** 10.28.2 (enforced via `only-allow pnpm` + corepack)
### Installation
```bash
# Enable corepack (ships with Node.js)
corepack enable
# Install all dependencies
pnpm install
```
### Development
```bash
# Start all apps in dev mode (Turborepo parallel)
pnpm dev
# Start individual apps
pnpm --filter web dev # Student platform → http://localhost:5173
pnpm --filter admin dev # Admin dashboard → http://localhost:8386
```
### Build
```bash
# Build all apps and packages
pnpm build
# Build a specific app
pnpm --filter web build
pnpm --filter admin build
```
### Code Quality
```bash
# Lint all workspaces
pnpm lint
# Format all files
pnpm format
# Biome check (lint + format + fixes)
pnpm check
```
## Environment Variables
### `apps/web`
Copy `.env.example` to `.env.local` and configure:
| Variable | Description | Default (dev) |
|---|---|---|
| `VITE_API_BASE_URL` | Backend REST API base URL | `http://localhost:4000` |
| `VITE_WS_URL` | WebSocket endpoint | `http://localhost:8080/ws` |
| `VITE_API_TIMEOUT` | API request timeout (ms) | `30000` |
### `apps/admin`
| Variable | Description |
|---|---|
| `VITE_CLERK_PUBLISHABLE_KEY` | Clerk authentication publishable key |
| `VITE_API_BASE_URL` | Backend REST API base URL |
---
## Docker
### Local Development
```bash
# Start dev containers (hot-reload enabled)
make up
# Stop
make down
```
### Local Production Preview
```bash
# Start production-like containers (NGINX serving static builds)
make up-prod
# Stop
make down-prod
```
### Useful Make Commands
| Command | Description |
|---|---|
| `make up` / `make down` | Start/stop dev containers |
| `make up-prod` / `make down-prod` | Start/stop prod containers |
| `make rebuild-web` | Rebuild web dev container (no cache) |
| `make rebuild-admin` | Rebuild admin dev container (no cache) |
| `make logs-web` | Tail web container logs |
| `make logs-admin` | Tail admin container logs |
| `make ps` | Show running dev containers |
| `make clean` | Prune Docker build cache |
| `make hard-clean` | Full Docker system prune |
### Container Architecture
```
┌─────────────────────────────────────────────┐
│ bitlearning-network │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ web (dev) │ │ admin (dev) │ │
│ │ Node 24 Alpine │ │ Node 24 Alpine │ │
│ │ :5173 │ │ :8386 │ │
│ └──────────────────┘ └──────────────────┘ │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ web (prod) │ │ admin (prod) │ │
│ │ NGINX Alpine │ │ NGINX Alpine │ │
│ │ :5173 │ │ :8386 │ │
│ └──────────────────┘ └──────────────────┘ │
└─────────────────────────────────────────────┘
```
Production images use multi-stage builds: `Node 24 Alpine` (build) → `NGINX Alpine` (serve).
---
## CI/CD
### GitHub Actions
| Workflow | Trigger | Purpose |
|---|---|---|
| `build.yml` | PR to `main`/`develop` | Build validation, PR status comments |
| `build-check-dependabot.yml` | Dependabot PRs to `develop` | Automated dependency update build checks |
| `deploy.yml` | Push to `main`/`develop` | Build Docker images → Push to Docker Hub → Deploy via Ansible |
### Jenkins (Alternative Pipeline)
The `Jenkinsfile` provides an alternative CI/CD path:
- PR builds on `develop` branch
- Docker image build & push on `main` branch
- Discord webhook notifications for build/deploy status
- Images pushed to Docker Hub: `hoangclw/bitlearning-web` and `hoangclw/bitlearning-admin`
### Deployment Flow
```
Push to main/develop
│
├── GitHub Actions
│ ├── Build web Docker image
│ ├── Build admin Docker image
│ ├── Push to Docker Hub
│ └── Deploy via Ansible to VPS
│
└── Jenkins (alternative)
├── Build source
├── Build & push Docker images
└── Notify Discord
```
### Infrastructure
Ansible playbooks in `infra/` handle production deployment:
- `app_deploy.yml` — Main deployment playbook
- `vault.yml` — Encrypted secrets (Ansible Vault)
- `inventory` — Target host definitions
---
## Tooling
| Tool | Purpose | Config |
|---|---|---|
| [Turborepo](https://turbo.build/) | Monorepo build orchestration & caching | `turbo.json` |
| [pnpm](https://pnpm.io/) | Package manager with workspace support | `pnpm-workspace.yaml` |
| [Biome](https://biomejs.dev/) | Linter + formatter (replaces ESLint + Prettier) | `biome.json` |
| [Lefthook](https://github.com/evilmartians/lefthook) | Git hooks (pre-commit auto-format) | `lefthook.yml` |
| [Vite](https://vite.dev/) | Build tool & dev server | Per-app `vite.config.ts` |
| [Vitest](https://vitest.dev/) | Unit & integration testing | Configured in web's `vite.config.js` |
| [Knip](https://knip.dev/) | Unused dependency/export detection | `apps/admin/knip.config.ts` |
| [EditorConfig](https://editorconfig.org/) | Consistent editor settings | `.editorconfig` |
---
## Dependency Graph
```
apps/web
├── @workspace/ui (workspace:*)
├── @workspace/lib (workspace:*)
└── @workspace/typescript-config (workspace:*)
apps/admin
└── @workspace/typescript-config (workspace:*)
packages/ui
└── @workspace/typescript-config (workspace:*)
packages/lib
└── @workspace/typescript-config (workspace:*)
```
> `apps/admin` currently uses its own UI components (Radix + shadcn pattern) rather than `@workspace/ui`. Migration to the shared library is possible.
---
## License
PROPRIETARY — All rights reserved.