From 9b43f90582c18b33f48993b7f8fb3787161a48c5 Mon Sep 17 00:00:00 2001 From: ganeshwhere Date: Thu, 5 Mar 2026 02:14:47 +0530 Subject: [PATCH 1/2] docs: add initial README files for the monorepo, web, and API applications. --- README.md | 217 +++++++++++++++++++++++++++++++++++++++++++++ apps/api/README.md | 109 +++++++++++++++++++++++ apps/web/README.md | 102 +++++++++++++++++++++ 3 files changed, 428 insertions(+) create mode 100644 README.md create mode 100644 apps/api/README.md create mode 100644 apps/web/README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..6d90fe2 --- /dev/null +++ b/README.md @@ -0,0 +1,217 @@ +# Team Flow + +Team Flow is a full-stack project management platform built as a Turborepo monorepo. +It includes: + +- `apps/web`: Next.js 15 frontend (App Router, Server Actions, NextAuth OAuth) +- `apps/api`: NestJS 10 backend (REST API, guards, Prisma, mail) +- `packages/types`: shared API/domain types used by both apps +- `packages/ui`: shared UI primitives +- `packages/config`: shared config package + +## Tech Stack + +- Monorepo: Turborepo + pnpm workspaces +- Frontend: Next.js 15, React 19, NextAuth v5 beta, Tailwind +- Backend: NestJS 10, Passport JWT +- Database: PostgreSQL + Prisma ORM +- Email: Resend + React Email +- Testing: Vitest (web) + Jest (api) + +## Monorepo Structure + +```txt +main/ +├── apps/ +│ ├── web/ +│ └── api/ +├── packages/ +│ ├── types/ +│ ├── ui/ +│ └── config/ +├── turbo.json +├── pnpm-workspace.yaml +└── package.json +``` + +## Prerequisites + +- Node.js 22+ +- pnpm 10+ +- Docker (recommended for local Postgres) + +## Environment Setup + +### 1) API env + +```bash +cp apps/api/.env.example apps/api/.env +``` + +Minimum required values to run core features: + +- `DATABASE_URL` +- `API_JWT_SECRET` +- `AUTH_BRIDGE_SECRET` +- `APP_URL` +- `PORT` + +For email features (team invites / assignment emails), also set: + +- `RESEND_API_KEY` +- `RESEND_FROM_EMAIL` + +### 2) Web env + +Use local env for Next.js dev: + +```bash +cp apps/web/.env.local.example apps/web/.env.local +``` + +Required: + +- `NEXTAUTH_SECRET` +- `NEXTAUTH_URL` +- `GOOGLE_CLIENT_ID` +- `GOOGLE_CLIENT_SECRET` +- `GITHUB_CLIENT_ID` +- `GITHUB_CLIENT_SECRET` +- `NEXT_PUBLIC_API_URL` +- `AUTH_BRIDGE_SECRET` + +Important: + +- `AUTH_BRIDGE_SECRET` must match between `apps/api/.env` and `apps/web/.env.local`. + +## Local Development Setup + +### 1) Install dependencies + +```bash +pnpm install +``` + +### 2) Start PostgreSQL (Docker) + +```bash +docker run --name projectdb -e POSTGRES_PASSWORD=pass -p 5432:5432 -d postgres +``` + +### 3) Prepare database schema and client + +```bash +pnpm --filter api prisma:generate +pnpm --filter api prisma:migrate +``` + +### 4) Seed demo data (optional) + +```bash +pnpm --filter api prisma:seed +``` + +### 5) Run both servers + +```bash +pnpm dev +``` + +## App URLs + +- Web: http://localhost:3000 +- API: http://localhost:4000 + +## OAuth Redirect URLs + +Set these in your OAuth provider dashboards: + +- Google callback: `http://localhost:3000/api/auth/callback/google` +- GitHub callback: `http://localhost:3000/api/auth/callback/github` + +## Core Scripts + +From repo root: + +- `pnpm dev` - run all apps in watch mode +- `pnpm lint` - monorepo type/lint checks +- `pnpm test` - monorepo tests +- `pnpm build` - monorepo build +- `pnpm ci` - lint + test + build +- `pnpm format` - prettier write +- `pnpm format:check` - prettier check + +Package-level examples: + +- `pnpm --filter api test` +- `pnpm --filter web test` + +## API Route Overview + +### Auth + +- `POST /auth/verify-token` + +### Users + +- `GET /users/me` + +### Teams + +- `GET /teams` +- `POST /teams` +- `GET /teams/:id` +- `PATCH /teams/:id` +- `DELETE /teams/:id` +- `POST /teams/:id/invite` +- `POST /teams/:id/join` +- `DELETE /teams/:id/members/:userId` + +### Projects + +- `GET /teams/:teamId/projects` +- `POST /teams/:teamId/projects` +- `GET /teams/:teamId/projects/:id` +- `PATCH /teams/:teamId/projects/:id` +- `DELETE /teams/:teamId/projects/:id` + +### Tasks + +- `GET /projects/:projectId/tasks` +- `POST /projects/:projectId/tasks` +- `GET /projects/:projectId/tasks/:id` +- `PATCH /projects/:projectId/tasks/:id` +- `DELETE /projects/:projectId/tasks/:id` + +### Project Chat + +- `GET /projects/:projectId/chat/messages` +- `POST /projects/:projectId/chat/messages` + +## Common Troubleshooting + +### Prisma authentication failed + +Verify `DATABASE_URL` user/password and that Postgres is running on the expected host/port. + +### NextAuth `JWTSessionError: no matching decryption secret` + +Your auth secret changed while old cookies still exist, or envs do not match. +Fix by ensuring correct `NEXTAUTH_SECRET` and clearing browser cookies for localhost. + +### Chat endpoint returns migration-related errors + +Run: + +```bash +pnpm --filter api exec prisma migrate deploy +pnpm --filter api prisma:generate +``` + +Then restart API. + +## Notes + +- The API uses OAuth user upsert flow via `POST /auth/verify-token` from the web app. +- API auth for app routes is token-based (Bearer token issued by API). +- Team invites and assignment emails are non-blocking (mail failures are logged, API continues). diff --git a/apps/api/README.md b/apps/api/README.md new file mode 100644 index 0000000..f831cbb --- /dev/null +++ b/apps/api/README.md @@ -0,0 +1,109 @@ +# Team Flow API (`apps/api`) + +NestJS 10 backend for Team Flow. + +## Responsibilities + +- OAuth user upsert bridge (`POST /auth/verify-token`) +- API JWT issuance and route protection +- Teams, projects, tasks, and project chat APIs +- Invite and task-assignment email orchestration (Resend) +- PostgreSQL persistence via Prisma + +## Prerequisites + +- Node.js 22+ +- pnpm 10+ +- PostgreSQL running and reachable from `DATABASE_URL` + +## Environment + +Create local env from template: + +```bash +cp .env.example .env +``` + +Key variables: + +- `DATABASE_URL` +- `API_JWT_SECRET` +- `AUTH_BRIDGE_SECRET` +- `APP_URL` +- `PORT` (default `4000`) + +Optional but recommended for email features: + +- `RESEND_API_KEY` +- `RESEND_FROM_EMAIL` +- `TEAM_INVITE_JWT_SECRET` + +## Database Setup + +From monorepo root: + +```bash +pnpm --filter api prisma:generate +pnpm --filter api prisma:migrate +pnpm --filter api prisma:seed +``` + +For deployed environments using existing migrations only: + +```bash +pnpm --filter api exec prisma migrate deploy +pnpm --filter api prisma:generate +``` + +## Run Locally + +From monorepo root: + +```bash +pnpm --filter api dev +``` + +API default URL: `http://localhost:4000` + +## Scripts + +- `pnpm --filter api dev` - run API in watch mode +- `pnpm --filter api build` - build Nest app +- `pnpm --filter api lint` - TypeScript checks +- `pnpm --filter api test` - Jest test suite +- `pnpm --filter api prisma:generate` - generate Prisma client +- `pnpm --filter api prisma:migrate` - create/apply migration (dev) +- `pnpm --filter api prisma:seed` - seed demo data + +## API Surface (High-Level) + +- Auth: `/auth/verify-token` +- Users: `/users/me` +- Teams: `/teams/...` +- Projects: `/teams/:teamId/projects/...` +- Tasks: `/projects/:projectId/tasks/...` +- Project chat: `/projects/:projectId/chat/messages` + +## Troubleshooting + +### Prisma auth/database errors + +Verify: + +- Postgres is running +- `DATABASE_URL` username/password/host/port/database are correct +- `schema=public` (if expected) is present + +### Invite emails fail + +The API is designed to keep core flows non-blocking on email failures. Confirm: + +- `RESEND_API_KEY` is valid +- `RESEND_FROM_EMAIL` domain is configured in Resend + +### 401/403 from protected routes + +Check: + +- API bearer token is issued by `/auth/verify-token` +- `AUTH_BRIDGE_SECRET` matches between web and api envs diff --git a/apps/web/README.md b/apps/web/README.md new file mode 100644 index 0000000..c2bc204 --- /dev/null +++ b/apps/web/README.md @@ -0,0 +1,102 @@ +# Team Flow Web (`apps/web`) + +Next.js 15 frontend for Team Flow (App Router + Server Actions). + +## Responsibilities + +- OAuth login via NextAuth (Google/GitHub) +- Protected dashboard routes and middleware checks +- Server Action layer for teams/projects/tasks/chat +- Task board, task detail, team management, notifications, settings views + +## Prerequisites + +- Node.js 22+ +- pnpm 10+ +- Running API (`apps/api`) reachable from `NEXT_PUBLIC_API_URL` + +## Environment + +Create local env from template: + +```bash +cp .env.local.example .env.local +``` + +Required variables: + +- `NEXTAUTH_SECRET` +- `NEXTAUTH_URL` (local: `http://localhost:3000`) +- `GOOGLE_CLIENT_ID` +- `GOOGLE_CLIENT_SECRET` +- `GITHUB_CLIENT_ID` +- `GITHUB_CLIENT_SECRET` +- `NEXT_PUBLIC_API_URL` (local: `http://localhost:4000`) +- `AUTH_BRIDGE_SECRET` + +Important: + +- `AUTH_BRIDGE_SECRET` must match `apps/api/.env`. + +## OAuth Callback URLs + +Configure in provider consoles: + +- Google: `http://localhost:3000/api/auth/callback/google` +- GitHub: `http://localhost:3000/api/auth/callback/github` + +## Run Locally + +From monorepo root: + +```bash +pnpm --filter web dev +``` + +Web default URL: `http://localhost:3000` + +## Scripts + +- `pnpm --filter web dev` - run Next.js dev server +- `pnpm --filter web build` - production build +- `pnpm --filter web lint` - TypeScript checks (`tsconfig.lint.json`) +- `pnpm --filter web test` - Vitest test suite + +## Feature Notes + +- Server Actions return `{ data, error }` and normalize API failures for UI safety. +- Task detail chat supports: + - realtime-like message append (server-backed writes) + - `@mention` suggestions and mention persistence + - responsive bubble layout and keyboard send (`Enter`) + +## Troubleshooting + +### NextAuth `JWTSessionError: no matching decryption secret` + +Usually caused by secret mismatch or stale cookies. + +- Ensure `NEXTAUTH_SECRET` is stable and correct. +- Clear localhost cookies/session and sign in again. + +### OAuth callback ends with configuration errors + +Check: + +- Provider client ID/secret values +- Callback URL exactly matches provider config +- `NEXTAUTH_URL` is correct for current environment + +### API calls fail with `ECONNREFUSED` + +Check: + +- API server is running on `NEXT_PUBLIC_API_URL` +- CORS and network target are correct + +### Login works but API routes fail + +Check: + +- `AUTH_BRIDGE_SECRET` is identical in web + api envs +- API `/auth/verify-token` is reachable From 09980a699c71748dcb12f50d0d203d3a9dd3549e Mon Sep 17 00:00:00 2001 From: ganeshwhere Date: Thu, 5 Mar 2026 02:27:14 +0530 Subject: [PATCH 2/2] docs: Add MIT license and contribution guidelines. --- CONTRIBUTING.md | 166 ++++++++++++++++++++++++++++++++++++++++++++++++ LICENSE | 21 ++++++ 2 files changed, 187 insertions(+) create mode 100644 CONTRIBUTING.md create mode 100644 LICENSE diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..22b61cf --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,166 @@ +# Contributing to Team Flow + +Thanks for contributing. + +This document defines contribution workflow, quality standards, and testing rules for this monorepo. + +## Table of Contents + +- [Prerequisites](#prerequisites) +- [Local Setup](#local-setup) +- [Branching and Commits](#branching-and-commits) +- [Coding Standards](#coding-standards) +- [Testing Policy](#testing-policy) +- [Database and Prisma Rules](#database-and-prisma-rules) +- [Pull Request Rules](#pull-request-rules) +- [Definition of Done](#definition-of-done) +- [Security and Secrets](#security-and-secrets) +- [License](#license) + +## Prerequisites + +- Node.js 22+ +- pnpm 10+ +- PostgreSQL (local or remote) + +## Local Setup + +1. Install dependencies: + +```bash +pnpm install +``` + +2. Create environment files: + +```bash +cp apps/api/.env.example apps/api/.env +cp apps/web/.env.local.example apps/web/.env.local +``` + +3. Prepare DB: + +```bash +pnpm --filter api prisma:generate +pnpm --filter api prisma:migrate +``` + +4. Run all apps: + +```bash +pnpm dev +``` + +## Branching and Commits + +- Branch from latest `main`. +- Branch naming: + - `feature/` + - `fix/` + - `chore/` +- Keep commits atomic and logically grouped. +- Use clear, outcome-based commit messages. +- Do not mix unrelated refactors with functional changes. + +## Coding Standards + +- Use TypeScript across apps/packages. +- Reuse contracts from `@repo/types`. +- Reuse shared primitives from `@repo/ui` where possible. +- Keep server actions typed and return predictable error/data contracts. +- Keep Nest modules cohesive and guarded at route boundaries. +- Prefer explicit, maintainable implementations over quick workarounds. + +## Testing Policy + +Testing is mandatory for behavior changes. + +### Required checks before PR + +From repo root: + +```bash +pnpm lint +pnpm test +pnpm build +``` + +### App-level expectations + +- API (`apps/api`, Jest): + - Add/update unit tests for service and guard logic changes. + - Add/update integration tests for route-contract or auth-flow changes. +- Web (`apps/web`, Vitest): + - Add/update tests for server actions and utility logic changes. + - Add/update integration tests for page/action flows when behavior changes. + +### Test quality rules + +- Tests must be deterministic (no flaky timing dependencies). +- Avoid network calls in unit tests; mock external dependencies. +- Keep assertions specific to behavior, not implementation noise. +- New features should include at least one positive-path and one failure-path test. + +### Running targeted tests + +```bash +pnpm --filter api test +pnpm --filter web test +``` + +## Database and Prisma Rules + +When changing `apps/api/prisma/schema.prisma`: + +- Generate migration with meaningful name: + +```bash +pnpm --filter api prisma:migrate +``` + +- Validate and regenerate client: + +```bash +pnpm --filter api prisma:validate +pnpm --filter api prisma:generate +``` + +- Update seed data if required by new schema constraints. +- Include migration impact notes in the PR description. + +## Pull Request Rules + +Each PR should include: + +- Clear summary and scope +- Why the change is needed +- Testing evidence (commands run + result) +- Migration notes (if DB changed) +- Screenshots/GIFs for user-facing UI changes + +Keep PRs reviewable: + +- Prefer smaller PRs +- Avoid unrelated formatting churn +- Resolve review comments with follow-up commits + +## Definition of Done + +A change is considered done when: + +- Code is implemented and reviewed +- Relevant tests are added/updated +- `pnpm lint`, `pnpm test`, and `pnpm build` pass +- No secrets or local env files are committed +- Documentation is updated when behavior/setup changes + +## Security and Secrets + +- Never commit `.env`, `.env.local`, tokens, secrets, or credentials. +- Redact sensitive values in logs and screenshots. +- Report security concerns privately to maintainers. + +## License + +By contributing, you agree that contributions are licensed under the +[MIT License](./LICENSE). diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..1a194f4 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Team Flow Contributors + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +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.