Getting Started — Admin UI

This guide walks you through running the Admin UI locally for development.

Prerequisites

Tool	Version	Notes
Node.js	20+	LTS recommended
pnpm	10+	npm i -g pnpm
Backend API	Running on port 8080	See Backend Getting Started

Clone & Install

git clone https://github.com/your-org/association-app-dashboard.git
cd association-app-dashboard
pnpm install

Environment Configuration

Create a .env.development file in the project root:

VITE_API_URL=http://localhost:8080
VITE_APP_NAME=Association App Admin (Dev)

# Firebase — only required if testing push notifications
VITE_FIREBASE_API_KEY=
VITE_FIREBASE_AUTH_DOMAIN=
VITE_FIREBASE_PROJECT_ID=
VITE_FIREBASE_STORAGE_BUCKET=
VITE_FIREBASE_MESSAGING_SENDER_ID=
VITE_FIREBASE_APP_ID=
VITE_FIREBASE_VAPID_KEY=

tip

Firebase variables are optional during local development. Push notifications simply won't work if they're omitted.

Run the Dev Server

pnpm dev

The app starts at http://localhost:5173 by default.

API requests to /api/* are automatically proxied to http://localhost:8080 via the Vite dev server proxy — no CORS configuration needed.

Project Structure

association-app-dashboard/
├── src/
│   ├── features/              # Feature modules
│   │   ├── auth/              # Authentication (store, hooks, pages)
│   │   ├── members/           # Members management
│   │   ├── events/            # Events management
│   │   ├── billing/           # Billing & payments (platform)
│   │   ├── organizations/     # Organisations (platform)
│   │   ├── connectors/        # Integrations
│   │   ├── articles/          # News & articles
│   │   └── documents/         # Document repository
│   ├── routes/                # TanStack Router route tree
│   │   ├── _platform/         # Platform admin routes
│   │   └── org.$slug/         # Organisation routes
│   ├── shared/
│   │   ├── components/        # Shared UI (Shadcn components)
│   │   └── lib/
│   │       └── api/           # HTTP client, types, auth
│   └── main.tsx
├── .env.development
├── .env.staging
├── .env.production
├── vite.config.ts
└── Dockerfile

Each feature follows a consistent module layout:

src/features/{feature}/
├── pages/         # Page-level React components
├── components/    # Feature-specific UI components
├── hooks.ts       # Custom React hooks
├── store.ts       # Zustand store
├── api.ts         # Axios API calls
└── types.ts       # TypeScript interfaces

Available Scripts

Command	Description
pnpm dev	Start dev server with HMR
pnpm build	TypeScript check + production build
pnpm preview	Preview the production build locally
pnpm lint	Run ESLint
pnpm format	Auto-fix formatting with Prettier
pnpm format:check	Check formatting without modifying files
pnpm knip	Detect unused exports and files

Logging In

Once the dev server and backend are running:

1. Navigate to http://localhost:5173
2. Choose your login context:
   • Platform Admin — for system-level access (/platform/login)
   • Organisation Member — for org-specific access (/org/:slug/login)
3. Enter credentials created via the backend seeder

info

The backend must be seeded with at least one platform admin user and one organisation before the Admin UI is fully usable. Refer to the backend getting started guide for seed commands.

IDE Setup

The project ships with Prettier and ESLint. For the best experience:

• VS Code: Install the Prettier and ESLint extensions, enable "Format on Save"
• JetBrains: Enable Prettier and ESLint in Settings → Languages & Frameworks

Path alias @/ resolves to ./src/ — supported by both the build tool and TypeScript.

Troubleshooting

Problem	Fix
Blank page after login	Check VITE_API_URL points to a running backend
401 on every request	Access token may be expired — clear cookies and log in again
TypeScript errors on start	Run pnpm build to see full diagnostics; router types are auto-generated
Proxy not working	Ensure backend runs on port 8080; the Vite proxy is only active in pnpm dev mode