diff --git a/apps/public/content/articles/cookieless-analytics.mdx b/apps/public/content/articles/cookieless-analytics.mdx
index 4abbd326..2aac0bbf 100644
--- a/apps/public/content/articles/cookieless-analytics.mdx
+++ b/apps/public/content/articles/cookieless-analytics.mdx
@@ -88,9 +88,7 @@ We built OpenPanel from the ground up with privacy at its heartβand with featu
```html
+
+```
+
+By doing this, all requests are sent to your domain first, bypassing adblockers that look for third-party tracking domains.
\ No newline at end of file
diff --git a/apps/public/content/docs/(tracking)/how-it-works.mdx b/apps/public/content/docs/(tracking)/how-it-works.mdx
new file mode 100644
index 00000000..760df3d8
--- /dev/null
+++ b/apps/public/content/docs/(tracking)/how-it-works.mdx
@@ -0,0 +1,190 @@
+---
+title: How it works
+description: Understanding device IDs, session IDs, profile IDs, and event tracking
+---
+
+## Device ID
+
+A **device ID** is a unique identifier generated for each device/browser combination. It's calculated using a hash function that combines:
+
+- **User Agent** (browser/client information)
+- **IP Address**
+- **Origin** (project ID)
+- **Salt** (a rotating secret key)
+
+```typescript:packages/common/server/profileId.ts
+export function generateDeviceId({
+ salt,
+ ua,
+ ip,
+ origin,
+}: GenerateDeviceIdOptions) {
+ return createHash(`${ua}:${ip}:${origin}:${salt}`, 16);
+}
+```
+
+### Salt Rotation
+
+The salt used for device ID generation rotates **daily at midnight** (UTC). This means:
+
+- Device IDs remain consistent throughout a single day
+- Device IDs reset each day for privacy purposes
+- The system maintains both the current and previous day's salt to handle events that may arrive slightly after midnight
+
+```typescript:apps/worker/src/jobs/cron.salt.ts
+// Salt rotation happens daily at midnight (pattern: '0 0 * * *')
+```
+
+When the salt rotates, all device IDs change, effectively anonymizing tracking data on a daily basis while still allowing session continuity within a 24-hour period.
+
+## Session ID
+
+A **session** represents a continuous period of user activity. Sessions are used to group related events together and understand user behavior patterns.
+
+### Session Duration
+
+Sessions have a **30-minute timeout**. If no events are received for 30 minutes, the session automatically ends. Each new event resets this 30-minute timer.
+
+```typescript:apps/worker/src/utils/session-handler.ts
+export const SESSION_TIMEOUT = 1000 * 60 * 30; // 30 minutes
+```
+
+### Session Creation Rules
+
+Sessions are **only created for client events**, not server events. This means:
+
+- Events sent from browsers, mobile apps, or client-side SDKs will create sessions
+- Events sent from backend servers, scripts, or server-side SDKs will **not** create sessions
+- If you only track events from your backend, no sessions will be created
+
+Additionally, sessions are **not created for events older than 15 minutes**. This prevents historical data imports from creating artificial sessions.
+
+```typescript:apps/worker/src/jobs/events.incoming-event.ts
+// Sessions are not created if:
+// 1. The event is from a server (uaInfo.isServer === true)
+// 2. The timestamp is from the past (isTimestampFromThePast === true)
+if (uaInfo.isServer || isTimestampFromThePast) {
+ // Event is attached to existing session or no session
+}
+```
+
+## Profile ID
+
+A **profile ID** is a persistent identifier for a user across multiple devices and sessions. It allows you to track the same user across different browsers, devices, and time periods.
+
+### Profile ID Assignment
+
+If a `profileId` is provided when tracking an event, it will be used to identify the user. However, **if no `profileId` is provided, it defaults to the `deviceId`**.
+
+This means:
+- Anonymous users (without a profile ID) are tracked by their device ID
+- Once you identify a user (by providing a profile ID), all their events will be associated with that profile
+- The same user can be tracked across multiple devices by using the same profile ID
+
+```typescript:packages/db/src/services/event.service.ts
+// If no profileId is provided, it defaults to deviceId
+if (!payload.profileId && payload.deviceId) {
+ payload.profileId = payload.deviceId;
+}
+```
+
+## Client Events vs Server Events
+
+OpenPanel distinguishes between **client events** and **server events** based on the User-Agent header.
+
+### Client Events
+
+Client events are sent from:
+- Web browsers (Chrome, Firefox, Safari, etc.)
+- Mobile apps using client-side SDKs
+- Any client that sends a browser-like User-Agent
+
+Client events:
+- Create sessions
+- Generate device IDs
+- Support full session tracking
+
+### Server Events
+
+Server events are detected when the User-Agent matches server patterns, such as:
+- `Go-http-client/1.0`
+- `node-fetch/1.0`
+- Other single-name/version patterns (e.g., `LibraryName/1.0`)
+
+Server events:
+- Do **not** create sessions
+- Are attached to existing sessions if available
+- Are useful for backend tracking without session management
+
+```typescript:packages/common/server/parser-user-agent.ts
+// Server events are detected by patterns like "Go-http-client/1.0"
+function isServer(res: UAParser.IResult) {
+ if (SINGLE_NAME_VERSION_REGEX.test(res.ua)) {
+ return true;
+ }
+ // ... additional checks
+}
+```
+
+The distinction is made in the event processing pipeline:
+
+```typescript:apps/worker/src/jobs/events.incoming-event.ts
+const uaInfo = parseUserAgent(userAgent, properties);
+
+// Only client events create sessions
+if (uaInfo.isServer || isTimestampFromThePast) {
+ // Server events or old events don't create new sessions
+}
+```
+
+## Timestamps
+
+Events can include custom timestamps to track when events actually occurred, rather than when they were received by the server.
+
+### Setting Custom Timestamps
+
+You can provide a custom timestamp using the `__timestamp` property in your event properties:
+
+```javascript
+track('page_view', {
+ __timestamp: '2024-01-15T10:30:00Z'
+});
+```
+
+### Timestamp Validation
+
+The system validates timestamps to prevent abuse and ensure data quality:
+
+1. **Future timestamps**: If a timestamp is more than **1 minute in the future**, the server timestamp is used instead
+2. **Past timestamps**: If a timestamp is older than **15 minutes**, it's marked as `isTimestampFromThePast: true`
+
+```typescript:apps/api/src/controllers/track.controller.ts
+// Timestamp validation logic
+const ONE_MINUTE_MS = 60 * 1000;
+const FIFTEEN_MINUTES_MS = 15 * ONE_MINUTE_MS;
+
+// Future check: more than 1 minute ahead
+if (clientTimestampNumber > safeTimestamp + ONE_MINUTE_MS) {
+ return { timestamp: safeTimestamp, isTimestampFromThePast: false };
+}
+
+// Past check: older than 15 minutes
+const isTimestampFromThePast =
+ clientTimestampNumber < safeTimestamp - FIFTEEN_MINUTES_MS;
+```
+
+### Timestamp Impact on Sessions
+
+**Important**: Events with timestamps older than 15 minutes (`isTimestampFromThePast: true`) will **not create new sessions**. This prevents historical data imports from creating artificial sessions in your analytics.
+
+```typescript:apps/worker/src/jobs/events.incoming-event.ts
+// Events from the past don't create sessions
+if (uaInfo.isServer || isTimestampFromThePast) {
+ // Attach to existing session or track without session
+}
+```
+
+This ensures that:
+- Real-time tracking creates proper sessions
+- Historical data imports don't interfere with session analytics
+- Backdated events are still tracked but don't affect session metrics
diff --git a/apps/public/content/docs/(tracking)/meta.json b/apps/public/content/docs/(tracking)/meta.json
new file mode 100644
index 00000000..5c7804c7
--- /dev/null
+++ b/apps/public/content/docs/(tracking)/meta.json
@@ -0,0 +1,3 @@
+{
+ "pages": ["sdks", "how-it-works", "..."]
+}
diff --git a/apps/public/content/docs/get-started/revenue-tracking.mdx b/apps/public/content/docs/(tracking)/revenue-tracking.mdx
similarity index 100%
rename from apps/public/content/docs/get-started/revenue-tracking.mdx
rename to apps/public/content/docs/(tracking)/revenue-tracking.mdx
diff --git a/apps/public/content/docs/sdks/astro.mdx b/apps/public/content/docs/(tracking)/sdks/astro.mdx
similarity index 100%
rename from apps/public/content/docs/sdks/astro.mdx
rename to apps/public/content/docs/(tracking)/sdks/astro.mdx
diff --git a/apps/public/content/docs/sdks/express.mdx b/apps/public/content/docs/(tracking)/sdks/express.mdx
similarity index 100%
rename from apps/public/content/docs/sdks/express.mdx
rename to apps/public/content/docs/(tracking)/sdks/express.mdx
diff --git a/apps/public/content/docs/sdks/index.mdx b/apps/public/content/docs/(tracking)/sdks/index.mdx
similarity index 100%
rename from apps/public/content/docs/sdks/index.mdx
rename to apps/public/content/docs/(tracking)/sdks/index.mdx
diff --git a/apps/public/content/docs/sdks/javascript.mdx b/apps/public/content/docs/(tracking)/sdks/javascript.mdx
similarity index 100%
rename from apps/public/content/docs/sdks/javascript.mdx
rename to apps/public/content/docs/(tracking)/sdks/javascript.mdx
diff --git a/apps/public/content/docs/sdks/kotlin.mdx b/apps/public/content/docs/(tracking)/sdks/kotlin.mdx
similarity index 100%
rename from apps/public/content/docs/sdks/kotlin.mdx
rename to apps/public/content/docs/(tracking)/sdks/kotlin.mdx
diff --git a/apps/public/content/docs/(tracking)/sdks/meta.json b/apps/public/content/docs/(tracking)/sdks/meta.json
new file mode 100644
index 00000000..9e414baf
--- /dev/null
+++ b/apps/public/content/docs/(tracking)/sdks/meta.json
@@ -0,0 +1,20 @@
+{
+ "title": "SDKs",
+ "pages": [
+ "script",
+ "web",
+ "javascript",
+ "nextjs",
+ "react",
+ "vue",
+ "astro",
+ "remix",
+ "express",
+ "python",
+ "react-native",
+ "swift",
+ "kotlin",
+ "..."
+ ],
+ "defaultOpen": false
+}
diff --git a/apps/public/content/docs/sdks/nextjs.mdx b/apps/public/content/docs/(tracking)/sdks/nextjs.mdx
similarity index 100%
rename from apps/public/content/docs/sdks/nextjs.mdx
rename to apps/public/content/docs/(tracking)/sdks/nextjs.mdx
diff --git a/apps/public/content/docs/sdks/python.mdx b/apps/public/content/docs/(tracking)/sdks/python.mdx
similarity index 100%
rename from apps/public/content/docs/sdks/python.mdx
rename to apps/public/content/docs/(tracking)/sdks/python.mdx
diff --git a/apps/public/content/docs/sdks/react-native.mdx b/apps/public/content/docs/(tracking)/sdks/react-native.mdx
similarity index 100%
rename from apps/public/content/docs/sdks/react-native.mdx
rename to apps/public/content/docs/(tracking)/sdks/react-native.mdx
diff --git a/apps/public/content/docs/sdks/react.mdx b/apps/public/content/docs/(tracking)/sdks/react.mdx
similarity index 100%
rename from apps/public/content/docs/sdks/react.mdx
rename to apps/public/content/docs/(tracking)/sdks/react.mdx
diff --git a/apps/public/content/docs/sdks/remix.mdx b/apps/public/content/docs/(tracking)/sdks/remix.mdx
similarity index 100%
rename from apps/public/content/docs/sdks/remix.mdx
rename to apps/public/content/docs/(tracking)/sdks/remix.mdx
diff --git a/apps/public/content/docs/sdks/script.mdx b/apps/public/content/docs/(tracking)/sdks/script.mdx
similarity index 94%
rename from apps/public/content/docs/sdks/script.mdx
rename to apps/public/content/docs/(tracking)/sdks/script.mdx
index 1a924466..3eda8a5d 100644
--- a/apps/public/content/docs/sdks/script.mdx
+++ b/apps/public/content/docs/(tracking)/sdks/script.mdx
@@ -15,7 +15,7 @@ Just insert this snippet and replace `YOUR_CLIENT_ID` with your client id.
```html title="index.html" /clientId: 'YOUR_CLIENT_ID'/
+
+```
+
+That's it! OpenPanel will now automatically track:
+- Page views
+- Visit duration
+- Referrers
+- Device and browser information
+- Location
+
+## Using a Framework?
+
+If you are using a specific framework or platform, we have dedicated SDKs that provide a better developer experience.
+
+
+ }
+ description="Optimized for App Router and Server Components"
+ />
+ }
+ description="Components and hooks for React applications"
+ />
+ }
+ description="Integration for Vue.js applications"
+ />
+ }
+ description="Universal JavaScript/TypeScript SDK"
+ />
+ }
+ description="Track mobile apps with React Native"
+ />
+ }
+ description="Server-side tracking for Python"
+ />
+
+
+## Explore all SDKs
+
+We support many more platforms. Check out our [SDKs Overview](/docs/sdks) for the full list.
+
diff --git a/apps/public/content/docs/get-started/meta.json b/apps/public/content/docs/get-started/meta.json
new file mode 100644
index 00000000..4bb85521
--- /dev/null
+++ b/apps/public/content/docs/get-started/meta.json
@@ -0,0 +1,8 @@
+{
+ "pages": [
+ "install-openpanel",
+ "track-events",
+ "identify-users",
+ "revenue-tracking"
+ ]
+}
diff --git a/apps/public/content/docs/get-started/track-events.mdx b/apps/public/content/docs/get-started/track-events.mdx
new file mode 100644
index 00000000..ad51b299
--- /dev/null
+++ b/apps/public/content/docs/get-started/track-events.mdx
@@ -0,0 +1,48 @@
+---
+title: Track Events
+description: Learn how to track custom events to measure user actions.
+---
+
+Events are the core of OpenPanel. They allow you to measure specific actions users take on your site, like clicking a button, submitting a form, or completing a purchase.
+
+## Tracking an event
+
+To track an event, simply call the `track` method with an event name.
+
+```javascript
+op.track('button_clicked');
+```
+
+## Adding properties
+
+You can add additional context to your events by passing a properties object. This helps you understand the details of the interaction.
+
+```javascript
+op.track('signup_button_clicked', {
+ location: 'header',
+ color: 'blue',
+ variant: 'primary'
+});
+```
+
+### Common property types
+
+- **Strings**: Text values like names, categories, or IDs.
+- **Numbers**: Numeric values like price, quantity, or score.
+- **Booleans**: True or false values.
+
+## Using Data Attributes
+
+If you prefer not to write JavaScript, you can use data attributes to track clicks automatically.
+
+```html
+
+```
+
+When a user clicks this button, OpenPanel will automatically track a `signup_clicked` event with the property `location: 'header'`.
+
diff --git a/apps/public/content/docs/index.mdx b/apps/public/content/docs/index.mdx
index 972d9109..8b469d36 100644
--- a/apps/public/content/docs/index.mdx
+++ b/apps/public/content/docs/index.mdx
@@ -1,111 +1,83 @@
---
-title: Introduction to OpenPanel
-description: Get started with OpenPanel's powerful analytics platform that combines the best of product and web analytics in one simple solution.
+title: What is OpenPanel?
+description: OpenPanel is an open-source web and product analytics platform that combines the power of Mixpanel with the ease of Plausible. Whether you're tracking website visitors or analyzing user behavior in your app, OpenPanel provides the insights you need without the complexity.
---
-## What is OpenPanel?
+import { UserIcon,HardDriveIcon } from 'lucide-react'
-OpenPanel is an open-source analytics platform that combines product analytics (like Mixpanel) with web analytics (like Plausible) into one simple solution. Whether you're tracking website visitors or analyzing user behavior in your app, OpenPanel provides the insights you need without the complexity.
+## β¨ Key Features
-## Key Features
+- **π Advanced Analytics**: Funnels, cohorts, user profiles, and session history
+- **π Real-time Dashboards**: Live data updates and interactive charts
+- **π― A/B Testing**: Built-in variant testing with detailed breakdowns
+- **π Smart Notifications**: Event and funnel-based alerts
+- **π Privacy-First**: Cookieless tracking and GDPR compliance
+- **π Developer-Friendly**: Comprehensive SDKs and API access
+- **π¦ Self-Hosted**: Full control over your data and infrastructure
+- **πΈ Transparent Pricing**: No hidden costs
+- **π οΈ Custom Dashboards**: Flexible chart creation and data visualization
+- **π± Multi-Platform**: Web, mobile (iOS/Android), and server-side tracking
-### Web Analytics
-- **Real-time data**: See visitor activity as it happens
-- **Traffic sources**: Understand where your visitors come from
-- **Geographic insights**: Track visitor locations and trends
-- **Device analytics**: Monitor usage across different devices
-- **Page performance**: Analyze your most visited pages
+## π Analytics Platform Comparison
-### Product Analytics
-- **Event tracking**: Monitor user actions and interactions
-- **User profiles**: Build detailed user journey insights
-- **Funnels**: Analyze conversion paths
-- **Retention**: Track user engagement over time
-- **Custom properties**: Add context to your events
+| Feature | OpenPanel | Mixpanel | GA4 | Plausible |
+|----------------------------------------|-----------|----------|-----------|-----------|
+| β
Open-source | β
| β | β | β
|
+| π§© Self-hosting supported | β
| β | β | β
|
+| π Cookieless by default | β
| β | β | β
|
+| π Real-time dashboards | β
| β
| β | β
|
+| π Funnels & cohort analysis | β
| β
| β
* | β
*** |
+| π€ User profiles & session history | β
| β
| β | β |
+| π Custom dashboards & charts | β
| β
| β
| β |
+| π¬ Event & funnel notifications | β
| β
| β | β |
+| π GDPR-compliant tracking | β
| β
| β** | β
|
+| π¦ SDKs (Web, Swift, Kotlin, ReactNative) | β
| β
| β
| β |
+| πΈ Transparent pricing | β
| β | β
* | β
|
+| π Built for developers | β
| β
| β | β
|
+| π§ A/B testing & variant breakdowns | β
| β
| β | β |
-## Getting Started
+β
* GA4 has a free tier but often requires BigQuery (paid) for raw data access.
+β** GA4 has faced GDPR bans in several EU countries due to data transfers to US-based servers.
+β
*** Plausible has simple goals
-1. **Installation**: Choose your preferred method:
- - [Script tag](/docs/sdks/script) - Quickest way to get started
- - [Web SDK](/docs/sdks/web) - For more control and TypeScript support
- - [React](/docs/sdks/react) - Native React integration
- - [Next.js](/docs/sdks/nextjs) - Optimized for Next.js apps
+## π Quick Start
-2. **Core Methods**:
- ```js
- // Track an event
- track('button_clicked', {
- buttonId: 'signup',
- location: 'header'
- });
+Before you can start tracking your events you'll need to create an account or spin up your own instance of OpenPanel.
- // Identify a user
- identify({
- profileId: 'user123',
- email: 'user@example.com',
- firstName: 'John'
- });
- ```
+
+ }
+ description="Create your account and workspace"
+ />
+ }
+ description="Get full control and start self-host"
+ />
+
-## Privacy First
+1. **[Install OpenPanel](/docs/get-started/install-openpanel)** - Add the script tag or use one of our SDKs
+2. **[Track Events](/docs/get-started/track-events)** - Start measuring user actions
+3. **[Identify Users](/docs/get-started/identify-users)** - Connect events to specific users
+4. **[Track Revenue](/docs/get-started/revenue-tracking)** - Monitor purchases and subscriptions
+
+## π Privacy First
OpenPanel is built with privacy in mind:
-- No cookies required
-- GDPR and CCPA compliant
-- Self-hosting option available
-- Full control over your data
+- **No cookies required** - Cookieless tracking by default
+- **GDPR and CCPA compliant** - Built for privacy regulations
+- **Self-hosting option** - Full control over your data
+- **Transparent data handling** - You own your data
-## Open Source
+## π Open Source
OpenPanel is fully open-source and available on [GitHub](https://github.com/Openpanel-dev/openpanel). We believe in transparency and community-driven development.
-## Need Help?
+## π¬ Need Help?
- Join our [Discord community](https://go.openpanel.dev/discord)
- Check our [GitHub issues](https://github.com/Openpanel-dev/openpanel/issues)
- Email us at [hello@openpanel.dev](mailto:hello@openpanel.dev)
-
-## Core Methods
-
-### Set global properties
-
-Sets global properties that will be included with every subsequent event.
-
-### Track
-
-Tracks a custom event with the given name and optional properties.
-
-#### Tips
-
-You can identify the user directly with this method.
-
-```js title="Example shown in JavaScript"
-track('your_event_name', {
- foo: 'bar',
- baz: 'qux',
- // reserved property name
- __identify: {
- profileId: 'your_user_id', // required
- email: 'your_user_email',
- firstName: 'your_user_name',
- lastName: 'your_user_name',
- avatar: 'your_user_avatar',
- }
-});
-```
-
-### Identify
-
-Associates the current user with a unique identifier and optional traits.
-
-### Increment
-
-Increments a numeric property for a user.
-
-### Decrement
-
-Decrements a numeric property for a user.
-
-### Clear
-
-Clears the current user identifier and ends the session.
diff --git a/apps/public/content/docs/meta.json b/apps/public/content/docs/meta.json
new file mode 100644
index 00000000..85833fa7
--- /dev/null
+++ b/apps/public/content/docs/meta.json
@@ -0,0 +1,16 @@
+{
+ "pages": [
+ "---Introduction---",
+ "index",
+ "---Get started---",
+ "...get-started",
+ "---Tracking---",
+ "...(tracking)",
+ "---API---",
+ "...api",
+ "---Self-hosting---",
+ "...self-hosting",
+ "---Migration---",
+ "...migration"
+ ]
+}
diff --git a/apps/public/content/docs/sdks/meta.json b/apps/public/content/docs/sdks/meta.json
deleted file mode 100644
index 0c4e11bf..00000000
--- a/apps/public/content/docs/sdks/meta.json
+++ /dev/null
@@ -1,5 +0,0 @@
-{
- "title": "SDKs",
- "pages": ["script", "web", "javascript", "nextjs", "react", "vue", "astro", "remix", "express", "python", "react-native", "swift", "kotlin"],
- "defaultOpen": true
-}
diff --git a/apps/public/content/docs/self-hosting/self-hosting.mdx b/apps/public/content/docs/self-hosting/self-hosting.mdx
index 578c0b5f..1b4ec1ff 100644
--- a/apps/public/content/docs/self-hosting/self-hosting.mdx
+++ b/apps/public/content/docs/self-hosting/self-hosting.mdx
@@ -76,7 +76,7 @@ The path should be `/api` and the domain should be your domain.
```html title="index.html"