Know your company type before you apply.
Site: https://knowyourithub.com
Repository standards for data verification, the database-first review workflow, API security, accessibility, and validation are documented in CONTRIBUTING.md.
Job seekers, especially people switching companies, often find scattered or vague information when comparing potential employers. This project gives a minimal, useful, and source-linked company view so visitors can decide faster and with less noise.
Core goal:
- Show only useful details that help career decisions.
- Keep the catalog verifiable with citations.
- Make community corrections easy through submit and feedback workflows.
- Company type (product, service, hybrid) is often unclear on job portals.
- Public discussions can be outdated, opinionated, or not source-backed.
- Candidates need one place with consistent structure and clear verification status.
- Searchable company profiles with category and verification status.
- Source-linked profile fields and data freshness metadata.
- Progress indicators for verified, in-progress, and awaiting-review entries.
- Submit and feedback forms for corrections and additions.
- Next.js 16 (App Router)
- React 19
- TypeScript 5
- Tailwind CSS 4
- Zod for schema validation
- Math CAPTCHA + anti-bot checks + rate limiting
- Nodemailer for notifications
- Vercel for deployment
- PostgreSQL
company_profiles, with one row per catalog company - data/companies.json for active portal submissions only (
awaiting_review/in_progress) - Optional PostgreSQL storage for submissions
- Local JSON-backed queue fallback for development; production review queues require PostgreSQL or Upstash Redis
- Optional PostgreSQL snapshots for catalog distribution to keep repo data private
flowchart TB
subgraph Frontend["Web App"]
UI["Next.js App Router pages"]
DATA["Catalog read: PostgreSQL company_profiles"]
end
subgraph APIs["Form and Queue APIs"]
SUBMIT["POST /api/submissions"]
FEED["POST /api/feedback"]
CONTACT["POST /api/contact"]
CAPTCHA["GET /api/captcha"]
QUEUE["GET /api/submissions/queue"]
end
subgraph Controls["Security and Controls"]
BOT["Honeypot + timing checks"]
LIMIT["Rate limiting"]
SAN["Input sanitization"]
MAIL["SMTP notifications"]
end
subgraph Storage["Persistence"]
PG[("PostgreSQL optional")]
JSONQ["Pending queue JSON fallback"]
end
UI --> DATA
UI --> SUBMIT
UI --> FEED
UI --> CONTACT
UI --> CAPTCHA
SUBMIT --> BOT --> LIMIT --> SAN --> MAIL
FEED --> BOT
CONTACT --> BOT
SUBMIT --> PG
SUBMIT --> JSONQ
QUEUE --> PG
QUEUE --> JSONQ
Files involved:
- app/api/submissions/route.ts or the submit handler entry point
- lib/api/submit-handler.ts
- lib/submissions.ts
- lib/subscribers.ts
Behavior:
- A visitor submits an add or edit request from the portal.
- The request is validated, sanitized, and checked for duplicate or already-known companies.
- The record is inserted into the review queue (
company_submissions) with statusawaiting_review. - The item is shown on the review page as awaiting review until a maintainer confirms the record.
- If the submitter opts in, their email is stored in
catalog_subscribersand they receive the welcome email.
Files involved:
- lib/submissions.ts
- lib/email-templates.ts
- app/api/submissions/queue/status/route.ts
- data/companies.json
Behavior:
- A maintainer opens the queue and updates the company record with verified details.
- The queue status moves from
awaiting_reviewtoin_progress. - The code keeps the queue row active and synchronizes the draft record into PostgreSQL.
- The profile stays in a pending state with
verificationStatusset toin_progressuntil final verification is complete. - The notification email is sent only to the original submitter for
in_progress, not to all subscribers. - This matches the handwritten flow from the note: it is a personal update to the submitter during verification.
Files involved:
Behavior:
- Once approval is complete, the queue item is set to
verified. - The verified company is removed from the review queue and added to the published catalog.
- The canonical profile is stored in PostgreSQL
company_profilesand read directly by the website. - A broadcast email is sent to all active subscribers for the verified company update.
- The URL should resolve to the final company details route such as
/companies/<slug>.
This project intentionally separates queue status from catalog profile status:
- Queue status:
awaiting_review,in_progress,verified,rejected - Catalog/profile status:
unverified,in_progress,verified
The mapping is:
awaiting_review->unverifiedin_progress->in_progressverified->verified
This keeps the admin review queue clean while still allowing the public catalog to show a simple status model.
The code was previously broadcasting every non-rejected status update to all subscribers. That was not aligned with the handwritten flow.
The logic has been corrected so that:
in_progresssends a mail only to the original submitterverifiedsends a mail to all subscribersawaiting_reviewdoes not broadcast to all subscribers
The notification behavior is now aligned with the three flow stages described above.
- Rate limiting for abuse prevention.
- Honeypot/timing bot detection.
- CAPTCHA challenge token verification.
- Input sanitization and suspicious-character rejection.
- CORS handling for cross-origin safety.
This project intentionally separates queue status from catalog profile status:
- Queue status:
awaiting_review,in_progress,verified,rejected - Catalog/profile status:
unverified,in_progress,verified
The mapping is:
awaiting_review->unverifiedin_progress->in_progressverified->verified
This keeps the admin review queue clean while still allowing the public catalog to show a simple status model.
The code was previously broadcasting every non-rejected status update to all subscribers. That was not aligned with the handwritten flow.
The logic has been corrected so that:
in_progresssends a mail only to the original submitterverifiedsends a mail to all subscribersawaiting_reviewdoes not broadcast to all subscribers
The notification behavior is now aligned with the three flow stages described above.
- Rate limiting for abuse prevention.
- Honeypot/timing bot detection.
- CAPTCHA challenge token verification.
- Input sanitization and suspicious-character rejection.
- CORS handling for cross-origin safety.
The canonical catalog is stored as one row per company in PostgreSQL company_profiles.
data/companies.json is intentionally small: it contains only active portal submissions that are
awaiting review or in progress.
Typical workflow:
- Draft a company profile (optionally via enrichment scripts).
- Validate details against official sources.
- Set category, verification status, and source links.
- Update lastVerified and related metadata.
- Synchronize the verified profile to PostgreSQL.
Helper scripts (examples):
- npm run enrich:wikidata -- "Company Name" slug
- scripts/merge-enrichments.mjs
- scripts/fill-remaining-gaps.mjs
The project uses automated email notifications to keep submitters and subscribers informed about company profile updates through the submission workflow.
Email notifications are sent at three key workflow stages:
Sent to: Original submitter
Trigger: When a company submission is first created
Purpose: Confirm receipt and provide submission reference
This email acknowledges the submitter's company profile contribution and confirms that their submission has been received and is awaiting review in the queue.
Sent to: Maintainer/admin
Trigger: When a new company submission is queued
Purpose: Alert the team about pending reviews
This notification ensures maintainers are aware of new company submissions that require verification and validation against official sources.
Sent to: All active subscribers
Trigger: When a company profile is verified and published
Purpose: Inform subscribers about newly verified company data
This email notifies subscribers that a company profile has been thoroughly reviewed and verified, making it available in the searchable catalog.
Email templates are managed in lib/email-templates.ts and sent via Nodemailer using SMTP configuration from environment variables:
SMTP_HOST— SMTP server addressSMTP_PORT— SMTP port (typically 587 or 465)SMTP_USER— SMTP authentication usernameSMTP_PASSWORD— SMTP authentication passwordSMTP_FROM— Sender email address
Email sending functions:
sendNewSubmissionEmail()— User acknowledgmentsendOwnerNotificationEmail()— Maintainer alertsendSubscriberNotificationEmail()— Subscriber broadcast
The project maintains data quality through periodic audits and sync verification to ensure the catalog stays accurate and consistent across storage layers.
Latest audit snapshot (audit-results.json):
{
"totalCompanies": 109,
"reference": "astrazeneca",
"inSync": 108,
"outOfSync": 0,
"auditedAt": "2026-07-23",
"results": []
}Audit Metrics:
- Total Companies: 109 company profiles in catalog
- In Sync: 108 profiles verified and synchronized between DB and JSON files
- Out of Sync: 0 discrepancies found
- Sync Status: ✅ 99.08% (108/109) consistency across storage layers
- Last Audit: July 23, 2026
The project includes validation checks for:
- Required fields presence (company name, category, website)
- Domain format validation
- URL validity and accessibility
- Tag and service description completeness
- Source link citation integrity
- Verification status consistency
The codebase includes diagnostic utilities to verify data consistency:
# Check database storage counts
npm run scripts/audit-company-storage.mjs
# Test database connection and retrieve metadata
npm run scripts/diagnose-company-storage-connection.mjsThese utilities help ensure:
- PostgreSQL database connectivity
- Accurate company profile counts
- Metadata consistency between local JSON and database
- No orphaned or duplicate records
When adding or updating company profiles, use:
# Research company via Wikidata API
node scripts/enrich-wikidata.mjs "Company Name" slugThis tool pulls structured data like founding year, official website, and company description from Wikidata and creates draft JSON files for manual review before integration.
npm install
cp .env.example .env.local
npm run dev- Start the app locally:
npm run dev
- Open the submit form on
/submitand create a company request. - Confirm the submission is stored in the review queue and visible on
/coming-soon. - Update the queue status via the moderation console or API.
- Test the three stages:
awaiting_reviewshows the item in the review queuein_progresssends a direct email to the submitter onlyverifiedpushes the company to the catalog and broadcasts to all subscribers
- Check the generated catalog and queue JSON files after each status change.
curl -X POST http://localhost:3000/api/submissions/queue/status \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <ADMIN_API_KEY>" \
-d '{
"id": "<submission-id>",
"status": "in_progress",
"companyName": "Newgen Software",
"companySlug": "newgen-software"
}'For a verified transition:
curl -X POST http://localhost:3000/api/submissions/queue/status \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <ADMIN_API_KEY>" \
-d '{
"id": "<submission-id>",
"status": "verified",
"companyName": "Newgen Software",
"companySlug": "newgen-software"
}'- Deploy target: Vercel
- Environment template: .env.example
- Production review queue persistence: configure PostgreSQL via DATABASE_URL, or both Upstash variables
- Local-only queue fallback: JSON file storage when neither persistence provider is configured
- Optional API hardening: ADMIN_API_KEY and CORS origins
- Review queue moderation: set REVIEW_QUEUE_PASSCODE (or use ADMIN_API_KEY as its fallback)
The published catalog is read directly from PostgreSQL. Local JSON files are used only for review-queue drafts and public development samples.
The local files are:
data/companies.json— active queue/profile draft entries and pending review entriesdata/pending.json— fallback queue used when DB is not available
The DB tables are:
company_submissions— review queue rowscompany_profiles— canonical, verified catalog rowscatalog_subscribers— subscriber email listcompany_catalog_metadata— catalog snapshot metadata
npm run companies:sync-dbThis syncs verified draft rows into company_profiles and marks matching submissions in company_submissions as verified. Published pages read company_profiles directly.
- Push the branch to GitHub.
- Deploy to Vercel.
- Configure
DATABASE_URLin the deployment environment. - The deployed app reads the latest verified profile data directly from
company_profiles.
cp .env.example .env.local
npm install
npm run devThen:
- submit a company from the UI
- review it in the moderation queue
- change the queue status from
awaiting_reviewtoin_progress - verify it as
verified - run
npm run companies:sync-dbto ensure DB and catalog data remain in sync - push the branch and redeploy application code when necessary; catalog data is served directly from the database
Catalog sync commands:
- npm run catalog:migrate-to-rows (one-time, backup-first migration from the legacy catalog)
- npm run companies:sync-db
Build behavior:
npm run builddoes not create or refresh a catalog cache.- Production deployments require
DATABASE_URLfor published catalog data.
Catalog row schema:
- db/catalog.sql
- db/companies.sql
- db/submissions.sql
Pull request database sync workflow:
- GitHub Actions workflow: .github/workflows/companies-db-sync.yml
- Triggers on branch pushes and pull requests when sync-related files change (data, db, scripts, package.json)
- Runs a single orchestration command:
npm run sync:workflow - Sequence inside
sync:workflow:npm run submissions:migrate-verifiednpm run companies:sync-dbnpm run public:sanitize-data
Required pipeline secrets/env for full DB-backed generation:
DATABASE_URL(required for published catalog reads and DB sync/migration)NEXT_PUBLIC_SITE_URL(recommended for generated links)SMTP_HOST,SMTP_PORT,SMTP_USER,SMTP_PASS,MAIL_FROM(required only if email delivery is expected during sync)
Notes:
- If
DATABASE_URLis missing, DB-dependent steps will fail or skip depending on script behavior. npm run buildreads no catalog data from local JSON files.
Important: data inside tracked files is public in git history when pushed.
If your catalog must stay private, use this approach:
- Keep sensitive catalog in an untracked private file (for example data/companies.private.json).
- Add private file patterns to .gitignore.
- Commit only a sanitized sample file for public repositories.
- If data was already committed, rotate/move sensitive values and rewrite history if legally required.
Current repository note:
- This codebase reads verified profiles from PostgreSQL
company_profilesand active review entries from data/companies.json. - To fully hide catalog content from public viewers, you must stop tracking sensitive data files and publish only sanitized data.
- Apply DB schema:
- Run db/catalog.sql on production PostgreSQL.
- Push current catalog snapshot to DB:
- npm run catalog:push-db
- Configure production
DATABASE_URL. - Deploy application.
- Validate catalog pages and search in production.
- After validation, remove tracked catalog from git history policy:
- Keep data/companies.json gitignored.
- Untrack existing file once team is ready: git rm --cached data/companies.json
For local/public development without private data:
- Keep data/companies.example.json in repo.
- it is used only to generate sanitized development data.
This order avoids downtime because existing app behavior remains unchanged while source-of-truth transitions to DB.
- Community-maintained directory; not affiliated with listed companies.
- Information can change over time; always cross-check with official sources before making career decisions.
- External references and brand names belong to their respective owners.
- This platform is informational and does not guarantee hiring outcomes.
Copyright (c) 2026 Nuthan Murarysetty. All trademarks and company names referenced in profiles remain property of their respective owners.
This repository currently includes an MIT license in LICENSE.
If your intent is to prevent others from forking/reusing code, MIT is not suitable. You should replace LICENSE with a restrictive/proprietary license before publishing that policy.
Until LICENSE is changed, usage rights are governed by the current LICENSE file.



