teamsync / FAQ.md
shahzaib24681012's picture
Full feature wave: AI, attendance moat, focus features, webhooks, polls, voice, 2FA, push + docs
bf075d5
|
Raw History Blame Contribute Delete
10.3 kB
# TeamSync β€” Tech FAQ: What We Use & Why
Companion to **GUIDE.md** (which explains *how* things work). This one answers the questions every new team member asks: *why did we pick X?* Read it before asking β€” and if your question isn't here, ask, then add the answer for the next person.
---
## Languages & Core Framework
**Q: What language is this written in?**
TypeScript β€” everywhere, frontend and backend. It's JavaScript with types: the editor catches mistakes (wrong argument, missing field, typo'd property) *while you type* instead of crashing at runtime. On a team with juniors, types are the cheapest bug prevention that exists.
**Q: Why Next.js? Why not plain React + a separate Express/NestJS backend?**
One project, one language, one deploy. Next.js gives us pages *and* API endpoints in the same codebase β€” a folder like `src/app/api/leave/route.ts` **is** the backend. A separate backend would mean two repos, two deploys, duplicated types, and CORS headaches, for zero benefit at our size. If TeamSync ever needed a big standalone API, the `lib/` logic would move over cleanly.
**Q: Why is there a custom `server.ts` instead of just running Next.js normally?**
Two reasons Next alone can't handle: **WebSockets** (real-time chat needs a persistent connection server β€” Socket.IO) and **cron jobs** (auto-checkout at day end, morning digests, task reminders). `server.ts` boots one Node process that does Next + Socket.IO + cron together.
---
## Data
**Q: Why PostgreSQL?**
Our data is deeply *relational* β€” users belong to workspaces, messages to hubs, cards to lists to boards, attendance to users and dates. Relational databases with foreign keys are built exactly for this. Postgres specifically because it's the most capable open-source option, free, and available everywhere (we use Neon's free tier in production).
**Q: What's Prisma and why not raw SQL?**
Prisma is the translator between TypeScript and the database. The whole schema lives in one readable file (`prisma/schema.prisma`), queries are typed (`prisma.card.findMany(...)` autocompletes and type-checks), and schema changes are one command (`npm run db:push`). Raw SQL would be faster to execute in rare hot paths but far slower to write safely β€” wrong trade for us.
**Q: Why are uploaded files stored *inside* the database? Isn't that bad practice?**
Usually you'd use S3-style object storage. But our free host **wipes its disk on every restart** β€” files on disk literally vanished daily. Database storage (with a 10 MB cap and compression before upload) means files survive forever on the free tier. `lib/storage.ts` keeps an S3-shaped interface so we can switch when there's budget. Pragmatism over dogma.
**Q: Why no Redis? Every tutorial uses Redis for presence/sessions.**
Redis earns its place when you run *multiple server instances* that need shared state. We run exactly one process, so in-memory Maps do the same job with zero infrastructure. `lib/realtime.ts` is written so a Redis adapter can slot in when we scale horizontally. Don't add infrastructure before the problem exists.
---
## Frontend
**Q: Why Tailwind CSS instead of normal CSS/SCSS files?**
Styles live *on the element* (`className="rounded-lg px-3 text-sm"`), so you never hunt through stylesheets or fight naming collisions, and deleting a component deletes its styles. Our whole theme system (6 accent palettes + dark mode) works by pointing Tailwind colors at CSS variables β€” change the variable, the entire app re-colors.
**Q: Why zustand for state? Why not Redux or Context?**
Redux is heavyweight ceremony for what we need; raw Context re-renders too much. Zustand is ~1 KB: one store (`lib/client/store.ts`) holding user, channels, presence, unread counts β€” components subscribe to just the slice they use. Simple enough that you can read the entire store file in two minutes.
**Q: Where do the icons/charts/fonts come from?**
Icons: **lucide-react** (the industry-standard line icon set β€” never use emojis as UI icons). Charts: **recharts** (declarative React charts). Fonts: **Manrope** for headings + **Inter** for body, self-hosted through `next/font` (no external font requests, no layout shift).
---
## Auth & Security
**Q: Why hand-rolled JWT auth instead of NextAuth/Auth.js or Clerk?**
We need auth deeply integrated with our own users table, roles, workspace membership, *and* the Socket.IO handshake. Libraries fight you at those edges. Ours is small and standard: bcrypt-hashed passwords, a 15-minute access token + 30-day rotating refresh token in httpOnly cookies. Google OAuth is ~150 lines in `lib/oauth.ts` β€” the flow is simpler than the libraries wrapping it.
**Q: How does "Sign in with Google" work?**
OAuth 2.0 authorization-code flow: we redirect to Google β†’ user approves β†’ Google redirects back with a code β†’ server exchanges it for the user's verified email + name β†’ we find-or-create the account β†’ issue our normal cookies. Keys live in env vars; the button auto-hides if they're missing.
**Q: How are the vault (Logins page) passwords protected?**
AES-256-GCM encrypted before touching the database, key from the `VAULT_KEY` env var. Reveals are permission-checked *server-side* and every reveal is written to the audit log. Note the honest limitation: the server can decrypt (it has to, to show passwords to allowed members) β€” it's a team vault, not a zero-knowledge manager like 1Password.
**Q: Where are permissions enforced?**
**Always on the server.** Every API route starts with a guard (`requireMember`, `requireBoardAccess`, role checks). The UI hiding a button is cosmetics; the API guard is the actual security. Never ship an endpoint without one.
---
## External Services & APIs
| Service | What for | Why this one |
|---|---|---|
| **Google OAuth** | Sign in with Google | Free, everyone has a Google account |
| **SendGrid** | Sending email (invites, resets, alerts) | Free 100/day tier, simple REST API. Without a key, emails print to the server console instead β€” the code path is identical (`lib/mailer.ts`) |
| **Neon.tech** | Production PostgreSQL | Genuinely free Postgres that doesn't expire |
| **Hugging Face Spaces** | Hosts the live app (Docker) | Free tier that allows WebSockets + a long-running server β€” rare combination. Trade-offs: sleeps when idle, ephemeral disk |
| **GitHub** | Code backup, review, collaboration | Every commit ever made is recoverable; interns work via branches + Pull Requests |
| **Google Gemini** | AI features (summaries, drafts, reports, rewrites) | Free-tier LLM, plain REST, one seam (`lib/ai.ts`). Buttons hide when no key |
We integrate **no other external APIs**. Everything else β€” chat, attendance engine, boards, search, notifications, polls, 2FA, web-push β€” is built in this repo.
**Q: How do the AI features work? Does Gemini see our data?**
Only what a feature needs for one request: "Catch me up" sends that hub's recent messages, "Draft with AI" sends your own day's activity. Nothing is stored by us beyond the response, every AI call goes through `lib/ai.ts` (rate-limited per user), and outputs carry an "AI can make mistakes" note. No key configured = no AI buttons, zero data leaves the server.
**Q: Why did we build 2FA ourselves instead of using a library?**
TOTP is a tiny, stable standard (RFC 6238) β€” ~80 lines of Node crypto in `lib/totp.ts`, compatible with every authenticator app. A dependency would be bigger than the implementation. Note: Google sign-in skips our 2FA on purpose, because Google already enforces its own.
**Q: How do push notifications work when the app is closed?**
Web-push: the browser registers a service worker (`public/sw.js`) and gives us a per-device subscription; the server sends signed messages (VAPID keys) through the browser vendor's push service. Respects Do Not Disturb and quiet hours. It's opt-in per device from Preferences.
---
## Rules That Exist Because We Got Burned
1. **Never run `npm audit fix --force`.** It once "fixed" us onto a breaking Next.js major and took the app down. Versions are pinned deliberately.
2. **Run `npm run build` before every release.** Production builds type-check more strictly than `npm run dev` β€” deploys have failed silently on errors dev mode never showed.
3. **Schema changes need TWO pushes** β€” local database *and* live (Neon). Forgetting the live one crashes production with "column does not exist".
4. **`.gitignore` folder patterns need a leading `/`.** A bare `uploads/` once silently excluded `src/app/api/uploads/` and a whole API route never reached production for weeks.
5. **Stop the dev server before `npm run db:push`** on Windows β€” Prisma can't swap files the server holds open.
6. **Never commit `.env`** β€” every secret goes in env vars locally and in Space secrets in production. If a secret leaks into chat/git, rotate it.
7. **Interns never touch `main` or deploy.** Work on your `team/<name>` branch β†’ Pull Request β†’ review β†’ merge. Only the owner runs `git push hf main`.
---
## Working Questions
**Q: Something's broken locally β€” what do I check first?**
In order: (1) the PowerShell window running the server β€” the real error is printed there; (2) the browser console (F12); (3) did you run `npm install` and `npm run db:push` after pulling new code?; (4) restart the dev server. Then ask β€” with the error text, not "it doesn't work."
**Q: How do I see what's actually in the database?**
`npm run db:studio` β€” a visual browser for every table. Read-mostly; be careful editing.
**Q: How do I find where a feature lives?**
Search the codebase for visible UI text (e.g. "Punctuality score") β€” it leads to the page, which leads to the API call, which leads to the route and lib. GUIDE.md Β§4 has the folder map.
**Q: Who decides naming β€” why "Hubs" and "People" instead of channels/DMs?**
Deliberate product decision to be distinct from Slack (branding + trade-dress caution). UI language says hubs/people/team; internal code and URLs still say channel/dm/employees β€” renaming code paths risks bugs for zero user value. Follow the same rule in new work: user-facing words come from the product vocabulary, code names stay stable.
---
*If you asked something not covered here, add the answer once you learn it β€” this file only stays useful if it grows.*