Skip to content

AGENTS.md

Latest commit

 

History

History
72 lines (56 loc) · 3.73 KB

AGENTS.md

File metadata and controls

72 lines (56 loc) · 3.73 KB

Repository Guidelines

Project Structure & Module Organization

openbase is a Nuxt 4 app with a filesystem-driven frontend and backend:

  • app/: UI code (pages/, components/, composables/, types/, middleware/, assets/css/main.css).
  • server/: API routes and backend utilities (server/api/**, server/utils/**, server/plugins/**).
  • db/: PostgreSQL schema (db/schema.sql) plus local SQLite artifacts used for data-source exploration.
  • public/: static assets.
  • documentation/: canonical location for all specs and technical docs

Use feature-local organization where possible (for example, dashboard logic stays under app/components/dashboard and matching routes under server/api/admin/dashboards).

UI Notice

  • Breadcrumb navigation is rendered in the global top bar (left side), not inside page content.
  • Set breadcrumbs via PageHeader breadcrumbs prop (or useTopBarBreadcrumbs() for pages not using PageHeader).
  • Do not add explanatory/helper copy in frontend forms, modals, or empty states unless explicitly requested in the task/spec. Default to concise labels and actions only.

Build, Test, and Development Commands

  • podman compose down: stop and remove the running stack.
  • podman compose build: rebuild images.
  • podman compose up: start app + PostgreSQL with schema bootstrap for the local stack.
  • After startup, run checks/tests from inside the Podman environment.

Coding Style & Naming Conventions

  • Language stack: TypeScript + Vue SFC.
  • Indentation: 2 spaces; keep formatting aligned with surrounding files.
  • Components: PascalCase filenames (for example, DashboardEditor.vue).
  • Nuxt route files: filesystem naming ([id].put.ts, [slug].vue) to define params/methods.
  • Identifiers: camelCase for variables/functions, UPPER_SNAKE_CASE for constants.

No dedicated ESLint/Prettier config is committed; consistency with existing code is required.

Testing Guidelines

E2E Tests (Playwright)

End-to-end tests live in e2e/ and use Playwright with Chromium.

Environment:

  • Use Podman containers for Playwright setup and execution.
  • Do not run host-level package manager commands for test setup or execution.

The Playwright config (playwright.config.ts) auto-starts the Nuxt dev server when not in CI. Set BASE_URL to override the target (default http://localhost:3000).

Writing tests:

  • Place test files in e2e/ with *.spec.ts naming.
  • Group related tests with test.describe().
  • Keep tests independent — each test should not depend on state from another.

General

  • Before every PR, run podman compose down, podman compose build, and podman compose up.
  • Manually verify critical flows: setup, admin auth, dashboard editing/sharing, and data-source browsing.
  • For unit tests (future), prefer *.test.ts naming and colocate by feature (for example, server/**/__tests__).

Commit & Pull Request Guidelines

  • When done, create a branch named feat/, commit all changes.
  • Push the branch, and open a PR against main with a description of what was changed and why.
  • Do NOT push directly to main.
  • Keep commits focused and logically grouped.
  • Preferred format: type(scope): summary (example: fix(auth): reject inactive admins).

PRs should include:

  • What changed and why.
  • Linked issue/spec reference from documentation/ (for example, documentation/spec.md section when relevant).
  • Verification steps run.
  • UI screenshots/GIFs for frontend changes.
  • Notes for schema/env changes (db/schema.sql, DATABASE_URL).

Security & Configuration Tips

  • Do not commit secrets or production credentials.
  • Keep connection strings in environment variables.
  • Treat db/*.db* files as local/dev artifacts, not source-of-truth data.