https://github.com/zhyd1997/callytics
A Simple Analytics Dashboard for Cal.com Users
https://github.com/zhyd1997/callytics
hacktoberfest nextjs prisma shadcn-ui tailwindcss
Last synced: 2 months ago
JSON representation
A Simple Analytics Dashboard for Cal.com Users
- Host: GitHub
- URL: https://github.com/zhyd1997/callytics
- Owner: zhyd1997
- Created: 2025-10-14T04:10:09.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2026-04-02T05:04:57.000Z (2 months ago)
- Last Synced: 2026-04-02T07:23:45.382Z (2 months ago)
- Topics: hacktoberfest, nextjs, prisma, shadcn-ui, tailwindcss
- Language: TypeScript
- Homepage: https://callytics.vercel.app
- Size: 6.66 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 14
-
Metadata Files:
- Readme: README.md
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Callytics ✨
Lightweight analytics for Cal.com workspaces. Callytics gives teams instant visibility into meetings, event types, and booking trends without maintaining a bespoke reporting stack. 📊
## Features 💡
- OAuth 2.0 flow for Cal.com accounts with stateful callback handling 🔐
- Postgres-backed waitlist capture powered by Prisma Accelerate 📨
- Interactive landing hero styled to mirror Cal.com's product aesthetic and OAuth CTA ⚡️
- Analytics dashboard refreshed with the Cal.com palette, motion charts, and dark-mode friendly glows 📈
- Turbopack-enabled Next.js 16 app router with Tailwind CSS v4 styling ⚡️
## Tech Stack 🛠️
- Next.js 16 (App Router, React 19, Turbopack)
- Tailwind CSS v4 with custom design tokens
- Prisma ORM + Accelerate extension targeting PostgreSQL
- Vercel Analytics snippet for production telemetry 📈
## Prerequisites ✅
- Node.js 18.18 or newer (Next.js 16 requirement)
- pnpm 8.x or newer
- PostgreSQL database for the waitlist table 🐘
- Cal.com OAuth client credentials for the token exchange flow 🔑
## Quick Start 🚀
1. Install dependencies: `pnpm install`
2. Duplicate `.env.example` (or create `.env.local`) and set the required variables listed below
3. Run database migrations: `pnpm prisma migrate dev`
4. Start the dev server: `pnpm dev` and visit [http://localhost:3000](http://localhost:3000) 🎯
The `preinstall` script runs `prisma generate` so the generated client is always in sync. Turbopack handles hot reloading during development.
### Environment Variables 🌱
| Variable | Required | Description | Default |
| --- | --- | --- | --- |
| `DATABASE_URL` | Yes | PostgreSQL connection string used by Prisma | – |
| `CAL_OAUTH_CLIENT_ID` | Yes | OAuth client ID from your Cal.com developer app | – |
| `CAL_OAUTH_CLIENT_SECRET` | Yes | OAuth client secret from Cal.com | – |
| `CAL_OAUTH_REDIRECT_URI` | Optional | Explicit redirect URI to override the auto-detected callback | `http://localhost:3000/api/cal/oauth/callback` |
| `CAL_OAUTH_TOKEN_ENDPOINT` | Optional | Alternate Cal.com token endpoint (sandbox/self-hosted) | `https://api.cal.com/v2/oauth/token` |
Optional variables only need to be set when you diverge from the default local flow.
### Cal.com OAuth Setup 🤝
- Register a **Confidential OAuth App** inside the Cal.com developer portal.
- Configure the redirect URI to `http://localhost:3000/api/cal/oauth/callback` (or your deployed domain).
- Copy the client ID and secret into your `.env.local`.
- During the auth redirect the callback verifies the `state` cookie and exchanges the code for access/refresh tokens at `CAL_OAUTH_TOKEN_ENDPOINT`. Tokens are returned to the caller and should be persisted securely (e.g., server-side store).
#### Automatic Token Refresh 🔄
Callytics automatically refreshes expired Cal.com access tokens:
- When server actions request an access token, the system checks if it's expired or within 5 minutes of expiry
- If expired, it automatically calls Cal.com's refresh token endpoint (`POST https://app.cal.com/api/auth/oauth/refreshToken`)
- The database is updated with new tokens transparently
- No manual intervention required - your API calls just work!
The refresh logic is implemented in `lib/auth/refresh-token.ts` and integrated into server actions via `getValidAccessToken(userId)`.
### Database & Prisma 🗄️
- Prisma schema lives in `prisma/schema.prisma` and generates the client under `app/generated/prisma`.
- Migrations are stored in `prisma/migrations`. Apply them with `pnpm prisma migrate dev` for local development or `pnpm prisma migrate deploy` in CI/CD.
- The waitlist module writes to the `waitlist_entries` table via `lib/dal/waitlist.ts`.
## Available Scripts 🧰
- `pnpm dev` – start the Next.js dev server with Turbopack
- `pnpm build` – run Prisma migrations (via `prebuild`) then build for production
- `pnpm start` – serve the production build
- `pnpm lint` – execute the repository ESLint configuration
- `pnpm prisma ` – forward arbitrary Prisma CLI commands (generate, migrate, studio, etc.)
## Project Structure 🧭
- `app/` – Next.js route handlers, layouts, API routes, and generated Prisma client
- `modules/` – UI modules
- `components/` – shared UI primitives (buttons, cards, theming controls)
- `lib/` – Prisma client factory, waitlist data access layer, and schemas
- `prisma/` – schema and migrations for the Postgres database
- `.agent/` – onboarding docs, Cal.com OpenAPI excerpt, and shared conventions
## Deployment ☁️
- Optimized for Vercel; environment variables must be defined in the project settings
- Ensure your production database and Cal.com OAuth redirect URIs match the deployed domain
- Replace or configure `@vercel/analytics` if you use a different analytics provider
## Useful Links 🔗
- [Cal.com OAuth 2.0 Docs](https://cal.com/docs/api-reference/v2/oauth-clients/)
- [Next.js App Router Docs](https://nextjs.org/docs/app)
- [Prisma Documentation](https://www.prisma.io/docs)
- [AGENTS.md](./AGENTS.md) – living brief for contributor onboarding