pingSubhajit · letraz-admin · Oct 31, 2025 · Oct 31, 2025
diff --git a/.gitignore b/.gitignore
@@ -1,50 +1,79 @@
-# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
-
-# dependencies
-/node_modules
-/.pnp
+# Dependencies
+node_modules/
+.pnp
 .pnp.js
 
-# testing
-/coverage
+# Testing
+coverage/
+*.log
+
+# Next.js
+.next/
+out/
+build/
+dist/
 
-# next.js
-/.next/
-/out/
+# Encore
+.encore/
 
-# env
-/.env
-/.env.old
-/.env.local
-/.env.development.local
-/.env.test.local
-/.env.production.local
+# Environment
+.env
+.env.*
+!.env.example
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+.env.sentry-build-plugin
 
-# production
-/build
+# Vercel
+.vercel
+
+# TypeScript
+*.tsbuildinfo
+next-env.d.ts
 
-# misc
+# IDE
+.idea/
+.vscode/
+.cursor/
+.zed/
+.kiro/
 .DS_Store
+
+# Misc
 *.pem
+*.swp
+*.swo
+*~
 
-# debug
+# Logs
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
+pnpm-debug.log*
 
-# vercel
-.vercel
+# Turbo
+.turbo/
 
-# typescript
-*.tsbuildinfo
-next-env.d.ts
+# Python (for letraz-server if needed)
+__pycache__/
+*.py[cod]
+*$py.class
+.Python
+*.so
+.venv/
+venv/
+ENV/
+.fonttools_venv/
 
-# IDE
-/.idea
-/.zed
-/.vscode
-/.cursor
-/.kiro
+# Terraform
+.terraform/
+*.tfstate
+*.tfstate.*
+*.tfvars
+!terraform.tfvars.example
+.terraform.lock.hcl
 
-# Sentry Config File
-.env.sentry-build-plugin
+# Bruno API client
+.dropstone/
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -29,3 +29,4 @@ We appreciate your interest in contributing to Letraz! While we can't accept ext
 ---
 
 *Last updated: August 2025*
+
diff --git a/LICENSE b/LICENSE
@@ -18,4 +18,5 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.
+
diff --git a/apps/admin/.env.example b/apps/admin/.env.example
@@ -0,0 +1,25 @@
+CLERK_SECRET_KEY=clerk_production_secret_key
+CONSUMER_API_KEY=api_key_that_consumer_will_call_this_app_with
+BACKEND_HOST=url_of_the_backend_service
+ADMIN_API_KEY=api_key_to_call_admin_apis_from_backend_with
+NEXT_PUBLIC_APP_URL=app_url_with_protocol
+OPENAI_API_KEY=key_for_calling_openapi_model_via_api
+NEXT_PUBLIC_LINEAR_CLIENT_ID=linear_client_id
+LINEAR_CLIENT_ID=linear_client_id
+LINEAR_CLIENT_SECRET=linear_client_secret
+
+LINEAR_API_KEY=linear_api_key
+LINEAR_TEAM_ID=linear_team_id
+
+CONVEX_DEPLOYMENT=convex_deployment_host
+NEXT_PUBLIC_CONVEX_URL=convex_url
+
+POSTHOG_PROJECT_ID=posthog_project_id
+POSTHOG_PERSONAL_API_KEY=posthog_personal_api_key
+POSTHOG_PROJECT_API_KEY=posthog_project_api_key
+
+GITHUB_APP_ID=github_app_id
+GITHUB_APP_PRIVATE_KEY=github_app_private_key
+GITHUB_APP_CLIENT_ID=github_app_client_id
+GITHUB_APP_CLIENT_SECRET=github_app_client_secret
+GITHUB_APP_SLUG=github_app_slug
diff --git a/apps/admin/.gitignore b/apps/admin/.gitignore
@@ -0,0 +1,44 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# env
+/.env
+/.env.old
+/.env.local
+/.env.development.local
+/.env.test.local
+/.env.production.local
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+
+# IDE
+/.idea
+/.zed
diff --git a/apps/admin/README.md b/apps/admin/README.md
@@ -0,0 +1,84 @@
+# Letraz Admin
+
+A Next.js-based administrative panel for the Letraz ecosystem, providing tools for PR generation, user management, and Linear integration.
+
+## Overview
+
+Letraz Admin is a web application that streamlines development workflows by automating pull request description generation from Linear issues and providing administrative utilities for user management within the Letraz platform.
+
+## Key Features
+
+- **PR Generation**: Automatically generate comprehensive pull request descriptions from Linear issues using OpenAI
+- **User Management**: Administrative API for checking user signup status and verification
+- **Linear Integration**: Seamless OAuth integration with Linear for issue management
+- **Authentication**: Secure user authentication powered by Clerk
+- **Dark Mode**: Built-in dark/light theme support
+- **Responsive Design**: Modern, mobile-friendly interface
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js 18+ or Bun
+- Linear account with API access
+- Clerk account for authentication
+- OpenAI API key
+
+### Installation
+
+1. Clone the repository:
+```bash
+git clone https://github.com/pingSubhajit/letraz-admin.git
+cd letraz-admin
+```
+
+2. Install dependencies:
+```bash
+bun install
+# or
+npm install
+```
+
+3. Set up environment variables:
+```bash
+cp .env.example .env.local
+```
+
+Configure the following environment variables:
+```
+CLERK_SECRET_KEY=your_clerk_secret_key
+NEXT_PUBLIC_APP_URL=current_url_of_the_app
+OPENAI_API_KEY=your_openai_api_key
+CONSUMER_API_KEY=your_admin_api_key
+LINEAR_CLIENT_ID=your_linear_client_id
+LINEAR_CLIENT_SECRET=your_linear_client_secret
+NEXT_PUBLIC_LINEAR_CLIENT_ID=your_linear_client_id
+```
+
+4. Run the development server:
+```bash
+bun dev
+# or
+npm run dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) to view the application.
+
+## Technologies Used
+
+- **Framework**: Next.js 15 with App Router
+- **Language**: TypeScript
+- **Authentication**: Clerk
+- **Styling**: Tailwind CSS
+- **UI Components**: Radix UI
+- **API Integration**: Linear SDK
+- **AI**: OpenAI API
+- **Icons**: Lucide React
+
+## License
+
+This project is proprietary software owned by Letraz.
+
+## Contact
+
+For questions or support, contact the Letraz development team.
diff --git a/apps/admin/WARP.md b/apps/admin/WARP.md
@@ -0,0 +1,106 @@
+# WARP.md
+
+This file provides guidance to WARP (warp.dev) when working with code in this repository.
+
+Project: Letraz Admin (Next.js 15 + TypeScript)
+
+Common commands
+- Install dependencies (Bun preferred):
+```bash path=null start=null
+bun install
+```
+
+- Start development server (Turbopack):
+```bash path=null start=null
+bun run dev
+```
+
+- Build production bundle:
+```bash path=null start=null
+bun run build
+```
+
+- Start production server (after build):
+```bash path=null start=null
+bun run start
+```
+
+- Lint:
+```bash path=null start=null
+bun run lint
+```
+
+- Lint and fix:
+```bash path=null start=null
+bun run lint:fix
+```
+
+- Tests:
+  - No test script is currently defined in package.json.
+  - If tests are added later (e.g., with Vitest or Jest), prefer Bun-compatible invocations (e.g., `bun test` or `bun run test`) and document how to run a single test here.
+
+Environment
+- Copy the example env file and set required variables:
+```bash path=null start=null
+cp .env.example .env.local
+```
+- Required keys (see .env.example for the full list):
+  - Clerk: CLERK_SECRET_KEY, NEXT_PUBLIC_APP_URL
+  - Linear: NEXT_PUBLIC_LINEAR_CLIENT_ID, LINEAR_CLIENT_ID, LINEAR_CLIENT_SECRET
+  - OpenAI: OPENAI_API_KEY
+  - Admin/backends: CONSUMER_API_KEY, BACKEND_HOST, ADMIN_API_KEY
+  - Convex: CONVEX_DEPLOYMENT, NEXT_PUBLIC_CONVEX_URL
+
+High-level architecture
+- Framework and routing
+  - Next.js 15 App Router under app/.
+  - Top-level layout at app/layout.tsx and global styles in app/globals.css.
+  - Route groups/pages:
+    - app/(dashboard)/team-management/page.tsx
+    - app/generate-pr/page.tsx
+    - app/settings/page.tsx
+    - app/waitlist/page.tsx
+    - app/login/page.tsx
+    - API route: app/api/generate/route.ts (PR description generation)
+
+- Authentication and providers
+  - Linear oAuth for authentication
+  - UI/theme via Tailwind CSS and Radix-based UI components in components/ui/.
+  - Global providers in components/providers/ (convex-provider.tsx, theme-provider.tsx).
+
+- Feature areas and components
+  - Generate PR: components/generate-pr/* (Linear OAuth/connect, issue selection, generation flow, PRDescription rendering).
+  - Settings: components/settings/* (GitHub App connection, repository management, tokens).
+  - Team Management: components/team-management/* (CRUD dialogs, actions, table interactions).
+  - Waitlist: components/waitlist/* (Clerk allowlist status and table).
+
+- Back-end/data layer
+  - Convex functions and schema in convex/.
+    - convex/schema.ts defines core tables: teamMembers, apiTokens, repositories, githubLinearMappings, githubPrMappings, webhookEvents with relevant indices.
+    - convex/*.ts implements server-side operations (e.g., repositories.ts, teamMembers.ts, apiTokens.ts).
+  - Server Actions in lib/actions/ (Next.js “use server”):
+    - waitlistActions.ts communicates with BACKEND_HOST (requires ADMIN_API_KEY), revalidates relevant paths.
+    - clerkAllowlistActions.ts integrates with Clerk server SDK for allowlist management.
+    - checkLinearAuth.ts reads Linear OAuth token from cookies.
+
+- External integrations
+  - OpenAI via ai-sdk (app/api/generate/route.ts) to generate PR descriptions from Linear Issue data using OPENAI_API_KEY.
+  - Linear via @linear/sdk for issue data and OAuth (frontend flow/components).
+  - GitHub:
+    - lib/github-api.ts wraps REST calls (user, repos, webhooks, branches, issues, PRs, labels, milestones). Uses either OAuth token (cookie github_access_token) or a GitHub App installation token.
+    - lib/github-app.ts manages GitHub App auth via @octokit/auth-app and @octokit/rest. Requires GITHUB_APP_ID and GITHUB_APP_PRIVATE_KEY (plus optional client ID/secret). Provides installation discovery and repo-scoped client acquisition.
+
+- Styling and build
+  - Tailwind configured in tailwind.config.ts and postcss.config.mjs.
+  - ESLint configured in eslint.config.mjs (flat config). Scripts: lint, lint:fix.
+  - TypeScript strict config; path alias @/* to project root.
+
+Operational notes for Warp
+- Use Bun for all script execution (Node isn’t required in this environment). Prefer `bun run <script>`.
+- Ensure .env.local is present with required variables before running dev or calling API routes (PR generation, waitlist actions, and GitHub App/Clerk flows depend on them).
+- Convex access uses environment-provided URLs (CONVEX_DEPLOYMENT, NEXT_PUBLIC_CONVEX_URL). There is no local Convex dev script in package.json.
+
+References from repository files
+- package.json scripts: dev (next dev --turbopack), build (next build), start (next start), lint, lint:fix.
+- app/api/generate/route.ts contains the OpenAI-driven PR generation flow using ai-sdk and @linear/sdk inputs.
+- convex/schema.ts defines core data model for team members, repositories, and GitHub/Linear mappings.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -29,3 +29,4 @@ We appreciate your interest in contributing to Letraz! While we can't accept ext
		---

		Last updated: August 2025