openstatus.dev
Openstatus
www.openstatus.dev
1# Agent.md
2
3This file provides a comprehensive overview of the OpenStatus project, its architecture, and development conventions to be used as instructional context for future interactions.
4
5## Project Overview
6
7OpenStatus is an open-source synthetic monitoring platform. It allows users to monitor their websites and APIs from multiple locations and receive notifications when they are down or slow.
8
9The project is a monorepo managed with pnpm workspaces and Turborepo. It consists of several applications and packages that work together to provide a complete monitoring solution.
10
11### Core Technologies
12
13- **Frontend:**
14 - Next.js (with Turbopack)
15 - React
16 - Tailwind CSS
17 - shadcn/ui
18 - tRPC
19- **Backend:**
20 - Hono (Node.js framework)
21 - Go
22- **Database:**
23 - Turso (libSQL)
24 - Drizzle ORM
25- **Data Analytics:**
26 - Tinybird
27- **Authentication:**
28 - NextAuth.js
29- **Build System:**
30 - Turborepo
31
32### Architecture
33
34The OpenStatus platform is composed of three main applications:
35
36- **`apps/dashboard`**: A Next.js application that provides the main user interface for managing monitors, viewing status pages, and configuring notifications.
37- **`apps/server`**: A Hono-based backend server that provides the API for the dashboard application.
38- **`apps/checker`**: A Go application responsible for performing the actual monitoring checks from different locations.
39
40These applications are supported by a collection of shared packages in the `packages/` directory, which provide common functionality such as database access, UI components, and utility functions.
41
42## Building and Running
43
44The project can be run using Docker (recommended) or a manual setup.
45
46### With Docker
47
481. Copy the example environment file:
49 ```sh
50 cp .env.docker.example .env.docker
51 ```
522. Start all services:
53 ```sh
54 docker compose up -d
55 ```
563. Access the applications:
57 - Dashboard: `http://localhost:3002`
58 - Status Pages: `http://localhost:3003`
59
60### Manual Setup
61
621. Install dependencies:
63 ```sh
64 pnpm install
65 ```
662. Initialize the development environment:
67 ```sh
68 pnpm dx
69 ```
703. Run a specific application:
71 ```sh
72 pnpm dev:dashboard
73 pnpm dev:status-page
74 pnpm dev:web
75 ```
76
77### Running Tests
78
79To run the test suite, use the following command:
80
81Before running the test you should launch turso dev in a separate terminal:
82```sh
83turso dev
84```
85
86Then, seed the database with test data:
87
88```sh
89cd packages/db
90pnpm migrate
91pnpm seed
92```
93
94Then run the tests with:
95
96```sh
97pnpm test
98```
99
100## Development Conventions
101
102- **Monorepo:** The project is organized as a monorepo using pnpm workspaces. All applications and packages are located in the `apps/` and `packages/` directories, respectively.
103- **Build System:** Turborepo is used to manage the build process. The `turbo.json` file defines the build pipeline and dependencies between tasks.
104- **Linting and Formatting:** The project uses Biome for linting and formatting. The configuration can be found in the `biome.jsonc` file.
105- **Code Generation:** The project uses `drizzle-kit` for database schema migrations.
106- **API:** The backend API is built using Hono and tRPC. The API is documented using OpenAPI.