GCS-SSC

GCS-SSC is an internal grants and contributions system designed to manage the lifecycle from agency setup to funding case agreements.

🎮 Live Demo

Experience the application immediately: Launch Demo Credentials:

• Username: root@example.com
• Password: password123

A real application would likely implement login via Office 365 or another OAuth provider, but username/password is used for demo purposes.

⚠️ Important Notes (WebContainers)

This demo uses WebContainers to run the full Node.js server and PostgreSQL database (PGlite) directly inside your browser tab. This will take a little bit too boot up, be patient.

1. Local Execution: No data is sent to a remote backend. Everything happens locally in your browser.
2. Persistence: Changes (e.g., creating users, editing records) are NOT saved if you refresh your browser or leave the app.
3. Resetting State: If you break the configuration, or an update has new migrations, or want to start fresh:
   • Clear Site Data: Go to your browser's DevTools -> Application -> Storage -> "Clear site data".
   • Incognito: Alternatively, open the link in a new Incognito/Private window for a disposable session.

📚 Documentation

CRITICAL: This project follows strict operating guidelines.

• AGENTS.md: The canonical operating manual. Read this first before contributing.
• specs/: Additional specifications.

🛠 Tech Stack

• Runtime: Bun
• Framework: Nuxt 4 + Vue 3 (Composition API)
• UI: Nuxt UI v4 (Tailwind-based)
• Database: PostgreSQL (PGlite in dev) + Kysely
• Auth: Better Auth
• Validation: Zod + useZodI18n
• Testing: Vitest (Unit) + Playwright (E2E)

🚀 Getting Started

Prerequisites

• Bun must be installed.

Installation

bun install

Development Server

Start the development server (defaults to port 3000):

bun run dev

Use bun run dev:clean to start with a fresh PGlite database.

Seeded Data

The development database comes pre-seeded with test users (Password: password123):

• Root Admin: root@example.com
• Agency User: agency@example.com
• Program User: program@example.com
• Standard Users: user03@example.com ... user20@example.com

✅ Testing & Quality

Feature work is incomplete without corresponding tests.

# Run all checks (Lint, Typecheck, Unit, E2E)
bun run test:all:manual

# Run Unit Tests
bun run test:unit

# Run E2E Tests
bun run test:e2e

🔐 Key Architectural Concepts

Authorization (RBAC)

Authorization is mandatory on all server routes.

• Scopes:
  • Global: System-wide access.
  • Agency: Restricted to a specific agency.
  • Entity: Restricted to a specific entity path (e.g., specific Transfer Payment).
• Implementation: Uses authorize(...) helper on the server and useCan() composable on the client.

Bilingualism

• All user-facing text must be internationalized (i18n).
• Database fields for names/descriptions must include _en and _fr suffixes.

Soft Deletion

• Core entities use _deleted boolean columns.
• Data is never permanently removed from the database via standard delete operations.

📂 Project Structure

• app/: Vue/Nuxt application code (pages, components, composables).
• server/: Server-side API routes and utilities.
• shared/: Types and schemas shared between client and server.
• tests/: Unit and E2E test suites.
• instructions.md: The Rulebook.