Admin App Overview

The BISO Sites Admin App is a comprehensive content management system (CMS) that enables administrators and editors to manage all aspects of the organization's digital presence.

Who uses this app?

• IT Manager / Super Admin – maintains configuration, permissions, and integrations.
• Content Editors – create pages, posts, events, shop listings, and department content.
• Developers – add new server actions, extend the page builder, or troubleshoot issues reported by editors.

Quick navigation

• Authentication & RBAC – login flows, middleware, and permission labels.
• User Management – CRUD actions for accounts and roles.
• Page Builder (Puck) – how drag-and-drop pages map to the public site.
• Content feeds – see how admin edits surface on the web app.

Feature map

Dependencies & integrations

• @repo/api – server actions and loaders use the shared Appwrite client.
• @repo/editor – the embedded Puck builder writes structured content consumed by the web app.
• @repo/ui – admin tables, forms, and dashboards use the shared component library.
• @repo/payment – order management ties directly into Vipps from the admin console.
• Operations → Appwrite – ensure roles/collections match what the admin app expects.

Admin workflows at a glance

Purpose & Features

The Admin App provides tools for:

1. User Management - Manage users, roles, and permissions
2. Content Management - Create and edit posts, news, pages
3. Event Management - Manage events, registrations, attendance
4. E-commerce Management - Products, orders, customers
5. Department Management - Units, teams, content
6. Job Board - Job postings and applications
7. Expense System - Internal expense tracking
8. Page Builder - Visual page editor with Puck

Technology Stack

• Next.js 15 - App Router
• React 19 - Server Components
• TypeScript - Type safety
• Tailwind CSS - Styling
• Appwrite - Backend (database, auth, storage)
• Puck - Visual page builder
• @repo/ui - Shared UI components

Architecture

Directory Structure

Authentication & Authorization

Role-Based Access Control

The admin app uses three primary roles:

1. Admin - Full access to all features
2. Editor - Content management access
3. Viewer - Read-only access

// Middleware protection
export async function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl;
  
  if (pathname.startsWith('/admin')) {
    const { account } = await createSessionClient();
    
    try {
      const user = await account.get();
      
      // Check if user has admin role
      if (!user.labels?.includes('admin') && !user.labels?.includes('editor')) {
        return NextResponse.redirect(new URL('/unauthorized', request.url));
      }
    } catch {
      return NextResponse.redirect(new URL('/auth/login', request.url));
    }
  }
  
  return NextResponse.next();
}

Dashboard

Route: /admin
File: app/(admin)/admin/page.tsx

The dashboard provides an overview of:

• Recent activity
• Pending registrations
• Order statistics
• User statistics
• Quick actions

// app/(admin)/admin/page.tsx
import { createSessionClient } from '@repo/api/server';
import { StatsCards } from '@/components/dashboard/stats-cards';
import { RecentActivity } from '@/components/dashboard/recent-activity';

export default async function AdminDashboard() {
  const { db } = await createSessionClient();
  
  // Fetch dashboard data
  const stats = await getDashboardStats(db);
  const recentActivity = await getRecentActivity(db);
  
  return (
    <div className="space-y-8">
      <h1 className="text-3xl font-bold">Dashboard</h1>
      <StatsCards stats={stats} />
      <RecentActivity activities={recentActivity} />
    </div>
  );
}

Key Features at a Glance

User Management

• User listing with search and filters
• User profile editing
• Role assignment
• Invitation system
• Activity tracking

Content Management

• Posts/News - Rich text editor, image uploads, publishing
• Events - Event editor with preview, registration tracking
• Pages - Visual page builder with Puck

E-commerce Management

• Products - Product editor with variations, images
• Orders - Order tracking, status updates
• Customers - Customer management
• Settings - Shop configuration

Other Features

• Units - Department management
• Jobs - Job posting and application tracking
• Expenses - Internal expense approval system

Navigation

The admin app uses a sidebar navigation layout:

// components/layout/admin-sidebar.tsx
export function AdminSidebar() {
  return (
    <aside className="w-64 border-r">
      <nav className="space-y-2 p-4">
        <SidebarLink href="/admin" icon={Home}>
          Dashboard
        </SidebarLink>
        <SidebarLink href="/admin/users" icon={Users}>
          Users
        </SidebarLink>
        <SidebarLink href="/admin/posts" icon={FileText}>
          Posts
        </SidebarLink>
        <SidebarLink href="/admin/events" icon={Calendar}>
          Events
        </SidebarLink>
        <SidebarLink href="/admin/pages" icon={Layout}>
          Pages
        </SidebarLink>
        <SidebarLink href="/admin/shop" icon={ShoppingCart}>
          Shop
        </SidebarLink>
        <SidebarLink href="/admin/units" icon={Building}>
          Units
        </SidebarLink>
        <SidebarLink href="/admin/jobs" icon={Briefcase}>
          Jobs
        </SidebarLink>
      </nav>
    </aside>
  );
}

Environment Variables

# Appwrite
NEXT_PUBLIC_APPWRITE_PROJECT_ID=your_project_id
NEXT_PUBLIC_APPWRITE_ENDPOINT=https://cloud.appwrite.io/v1
APPWRITE_API_KEY=your_admin_api_key

# Application
NEXT_PUBLIC_BASE_URL=http://localhost:3001

Port Configuration

• Development: http://localhost:3001
• Production: Configured via hosting

Quick Start

cd apps/admin
bun install
bun run dev
# Visit http://localhost:3001

Related Documentation

• Authentication - Auth flows and roles
• Content Management - Managing content
• User Management - Managing users
• Shop Management - E-commerce admin
• @repo/editor Package - Page builder