• Hasir Dashboard
  • Table of Contents
  • Overview
  • Features
  • Tech Stack
    • Core
    • Data & Communication
    • UI & Styling
    • Forms & Validation
    • Development Tools
  • Getting Started
    • Prerequisites
    • Installation
    • Environment Variables
    • Running the Application
  • Development
    • Project Structure
    • Code Quality
    • Testing
  • Deployment
    • Docker
    • Production Build
  • Architecture
    • Transport Layer
    • Authentication
    • State Management
    • Routing
  • Contributing
    • Commit Convention
  • License

Hasir Dashboard is a modern, full-featured web application built with Next.js 16 that serves as the frontend interface for an on-premise protobuf schema registry. It provides a seamless user experience for managing and browsing protocol buffer schemas with real-time updates via gRPC-web.

The application leverages cutting-edge React patterns including server components, streaming, and the latest Next.js App Router features to deliver optimal performance and developer experience.

• Schema Management: Browse, search, and manage protobuf schemas
• Real-time Updates: Live schema updates via gRPC-web transport
• Authentication: Secure JWT-based authentication with refresh tokens
• Dark Mode: Full dark/light theme support
• Responsive Design: Mobile-first responsive UI using Tailwind CSS
• Type-Safe: End-to-end type safety with TypeScript and generated protobuf types
• Modern UI: Built with shadcn/ui components and Radix UI primitives
• Fast Development: Turbopack-powered dev server for instant feedback
• Comprehensive Testing: Full test coverage with Vitest and React Testing Library

• Next.js 16 - React framework with App Router
• React 19 - UI library with latest features
• TypeScript 5 - Type-safe JavaScript

• Connect-RPC - gRPC-web client
• TanStack Query - Server state management
• Zustand - Client state management

• Tailwind CSS 4 - Utility-first CSS
• shadcn/ui - Re-usable component library
• Radix UI - Accessible UI primitives
• Lucide Icons - Icon library
• Framer Motion - Animation library

• React Hook Form - Performant forms
• Zod - Schema validation

• Bun - Fast JavaScript runtime
• Vitest - Unit testing framework
• ESLint - Code linting
• Turbopack - Fast bundler

• Bun >= 1.0 (or Node.js >= 18)
• Git

1. Clone the repository:

git clone https://github.com/lynicis/hasir-dashboard.git
cd hasir-dashboard

2. Install dependencies:

bun install

Create a .env file in the root directory:

cp .env.example .env

Configure the following environment variables:

# Backend API URL (gRPC-web endpoint)
NEXT_PUBLIC_API_URL=http://localhost:8080
# Frontend base URL
NEXT_PUBLIC_BASE_URL=http://localhost:3000

Start the development server:

bun dev

The application will be available at http://localhost:3000.

hasir-dashboard/
├── app/ # Next.js App Router pages and layouts
│ ├── (authenticated)/ # Protected routes group
│ ├── login/ # Login page
│ └── providers.tsx # App-level providers
├── components/ # React components
│ ├── ui/ # shadcn/ui components
│ └── *.tsx # Feature components
├── lib/ # Utility functions and helpers
│ ├── use-client.ts # Connect-RPC client hook
│ └── utils.ts # Common utilities
├── stores/ # Zustand state stores
│ └── user-store.ts # User authentication store
├── public/ # Static assets
└── tests/ # Test utilities and setup

Run the linter:

# Check for issues
bun run lint
# Auto-fix issues
bun run lint:fix

The project uses:

• ESLint with Next.js recommended config
• Perfectionist plugin for consistent import/export ordering
• TypeScript strict mode for type safety

Run tests:

# Watch mode
bun test
# CI mode with coverage
bun run test:ci

Tests are written using:

• Vitest for test running
• React Testing Library for component testing
• @testing-library/user-event for user interaction simulation

All components should have corresponding .test.tsx files with comprehensive test coverage.

Build and run with Docker:

# Build image
docker build -t hasir-dashboard .
# Run container
docker run -p 3000:3000 -e NEXT_PUBLIC_API_URL=http://your-api:8080 hasir-dashboard

Create an optimized production build:

# Build the application
bun run build
# Start production server
bun start

The build output is configured for standalone mode, making it ideal for containerized deployments.

The application uses Connect-RPC (gRPC-web) for backend communication:

• Transport configured in app/providers.tsx
• Binary wire format for optimal performance
• Custom useClient hook in lib/use-client.ts
• Generated protobuf types from @buf/hasir_hasir.bufbuild_es

// Example usage
import { useClient } from '@/lib/use-client';
import { SchemaService } from '@buf/hasir_hasir.connectrpc_es/schema/v1/service_connect';
const client = useClient(SchemaService);

JWT-based authentication with the following features:

• Access and refresh token pair
• Tokens stored in HTTP-only cookies (7-day expiration)
• Automatic token refresh on expiration
• User state managed via Zustand store
• Protected routes using route groups

Authentication flow:

1. User logs in via /login
2. Server returns JWT tokens stored in cookies
3. Tokens included automatically in subsequent requests
4. Refresh token used to obtain new access token when expired

Global State (Zustand):

• User authentication state
• User profile data
• Session management

Server State (TanStack Query):

• Data fetching and caching
• Optimistic updates
• Background refetching
• Request deduplication

UI State:

• Local component state using React hooks
• Form state via React Hook Form
• Theme preference via next-themes

The application uses Next.js App Router with route groups:

Public Routes:

• /login - User login
• /register - User registration
• /invite/[token] - Accept invitation

Authenticated Routes (/(authenticated)/):

• /dashboard - Main dashboard
• /profile - User profile management

Contributions are welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests and linting (bun test && bun run lint)
5. Commit your changes (git commit -m 'feat: add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

This project follows Conventional Commits:

• feat: - New features
• fix: - Bug fixes
• docs: - Documentation changes
• style: - Code style changes (formatting, etc.)
• refactor: - Code refactoring
• test: - Test additions or changes
• chore: - Build process or auxiliary tool changes

This project is licensed under the MIT License - see the LICENSE file for details.