Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 38 additions & 0 deletions .cursor/00-overview.mdc
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
---
description: Overview rules for Hawk monorepo - always applied
alwaysApply: true
---
# Hawk — Project Overview

Hawk is an error monitoring and observability platform for applications and services.
It is an open-source.

Primary goals of Hawk:
- Collect, store, and analyze application errors
- Help teams detect regressions and production issues early
- Provide actionable context (stack traces, metadata, releases, environments)

## Mono-repository structure

This is a mono-repository consisting of the separate GitHub sub-repostories.
It is used for development purposes but also can be used to self-host Hawk.

## Architecture

See rules for architecture in `.cursor/11-arch.mdc`.

## Documentation

Detailed feature documentation lives in:
- `docs/` — source of truth for specs and flows

## When modifying code

Before making changes:
1. Identify which layer you are working in: Catcher(SDK), API, Garage, Workers, Collector
2. Check related documentation in root `docs/` directory or in the service's own `docs/` directory
3. Preserve existing public APIs unless explicitly instructed

## Full Hawk Features Overview

See [Hawk Usage Guide](../docs/hawk-usage-guide-ru.md) for full features overview.
18 changes: 18 additions & 0 deletions .cursor/11-arch.mdc
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
---
description: Architecture rules for Hawk monorepo - always applied
alwaysApply: true
---
## Architecture (high level)

Hawk consists of:
- SDKs / Catchers (JS, Node.js, PHP, Python, etc.)
- API backend (event ingestion, processing, grouping) — GraphQL API
- Database (events, issues, users, projects) — MongoDB
- Garage — Web UI (dashboard, issues, charts, settings) — Vue.js 3
- Workers — Background tasks (email, Telegram, Slack notifications) — Node.js
- Collector — Entry point for all error events from client applications — Go
- Accounting — it is disabled and not used, do not use it in your code and memory

Some parts are split into separate repositories/packages but work as a single system.

Detailed description of the system architecture is in [docs/architecture.md](../docs/architecture.md).
3 changes: 3 additions & 0 deletions .cursor/22-commands.mdc
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
---
alwaysApply: true
---
3 changes: 3 additions & 0 deletions .cursor/33-style.mdc
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
---
alwaysApply: true
---
101 changes: 101 additions & 0 deletions .cursor/44-api.mdc
Original file line number Diff line number Diff line change
@@ -0,0 +1,101 @@
---
description: API service rules - GraphQL, models, SSO, billing
globs: ["api/**"]
---

# Hawk API Service - Rules for Cursor

Hawk API service (`api/`) is the main GraphQL API for frontend and external integrations.

## Technologies

- **Node.js/TypeScript**
- **GraphQL** (Apollo Server)
- **Express**
- **MongoDB** (through `mongodb` driver)
- **RabbitMQ** (for integration with workers)
- **JWT** for authentication

## Structure

```
api/
├── src/
│ ├── models/ # MongoDB models
│ ├── resolvers/ # GraphQL резолверы
│ ├── typeDefs/ # GraphQL schema
│ ├── directives/ # GraphQL directives
│ ├── billing/ # Billing integration
│ ├── sso/ # SSO functionality (SAML)
│ ├── utils/ # Utilities
│ └── types/ # TypeScript types
├── test/ # Tests
│ └── integration/ # Integration tests
└── migrations/ # MongoDB migrations
```

## Data models

Модели находятся в `src/models/`:
- Inherit from `AbstractModel`
- Model factories inherit from `AbstractModelFactory`
- Use MongoDB collections directly

## GraphQL

- **Schema**: `src/typeDefs/` — type definitions
- **Resolvers**: `src/resolvers/` — query logic
- **Directives**: `src/directives/` — validation and authorization

Important directives:
- `@requireAdmin` — requires admin rights
- `@requireUserInWorkspace` — requires user involvement in workspace
- `@allowAnon` — allows anonymous access. Used for auth queries.

## SSO (Single Sign-On)

**Important**: SSO is fully described in the documentation:

- **[SSO Specification](../docs/sso.md)** — full SSO functionality specification
- **[SSO Implementation Plan](../docs/sso-implementation.md)** — detailed implementation plan
- **[SSO Testing Guide](../docs/sso-testing-guide.md)** — testing guide

## Billing

We use CloudPayments for billing.

Detailed documentation is in [docs/billing/README.md](../docs/billing/README.md).

Code is in `src/billing/`.

Cloudpayments webhooks are handled not by GraphQL, but regular express routes handlers in `src/billing/cloudpayments.ts`.

## Testing

- **Unit tests**: `test/models/`, `test/resolvers/`, `test/utils/`
- **Integration tests**: `test/integration/`


## Migrations

We need to write migration when we change the database schema.

Use following command to create a new migration:

```bash
yarn migrations:create {migrationName}
```

Use following command to apply a new migration:

```bash
yarn migrations:up
```

Use following command to rollback the last migration:

```bash
yarn migrations:down
```

Migrations are stored in `migrations/` directory.
73 changes: 73 additions & 0 deletions .cursor/55-garage.mdc
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
---
description: Garage frontend rules - Vue.js 3, Vuex, GraphQL client
globs: ["garage/**"]
---

# Hawk Garage Service - Rules for Cursor

Hawk Garage (`garage/`) is web app for Hawk.

## Technologies

- **Vue.js 3** (Composition API + Options API)
- **TypeScript**
- **Vite** (builder)
- **Vuex** (state management)
- **Vue Router** (routing)
- **GraphQL** (Apollo Client for API requests)
- **Storybook** (for components)

## Structure

```
garage/
├── src/
│ ├── components/ # Vue components
│ ├── views/ # Pages (routes)
│ ├── store/ # Vuex store модули
│ ├── router/ # Vue Router configuration
│ ├── api/ # GraphQL client and queries
│ ├── i18n/ # Internationalization
│ ├── styles/ # Global styles
│ └── utils/ # Utilities
├── public/ # Static files
└── config/ # Configuration
```

## Components

- Vue 3 components (`.vue` files)
- Always use `<script setup>` and TypeScript for new components.

## State Management (Vuex)

Vuex store modules in `src/store/modules/`:
- `user` — current user
- `workspace` — workspaces
- `project` — projects
- Other modules by domains

Actions types are defined in `actionTypes.js` files of modules.

## API calls

- Always use `api.call()` for API calls. Never use `api.callOld()`.
- API responses should be handled on Store level. Filter and handle errors there.


## Internationalization

- Always move all UI tokens to i18n.
- Always fill all translations in `messages/` files.

## Styles

- Global styles in `src/styles/`
- Component styles via `<style>` blocks in `.vue` files
- Possible support for CSS preprocessors
- Always use nesting in styles.
- Use BEM notation for component classes:
- `block`
- `block__element`
- `block__element-child`
- `block__element-child--modifier`
32 changes: 32 additions & 0 deletions .cursorignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
# dependencies
node_modules/

# some docs for end-user
docs/how-to-get-events.md
docs/how-to-run-local-hawk.md
docs/how-to-view-registry-queues.md

# Legacy modules
accounting/
yard/

# build output
dist/
build/
coverage/
.tmp/
.cache/

# logs & dumps
*.log
*.heapprofile
*.cpuprofile
dump/

# generated data
*.map
*.min.js
*.lock

# sensitive data
.env
3 changes: 0 additions & 3 deletions docs/pull-database.md

This file was deleted.