Lynk is a campus collaboration and work platform connecting verified university students with projects, modular workspaces, team roles, and peer reviews. Built around a Unified Campus Member model, any verified student can create project workspaces, invite teammates, and submit direct applications under a single academic identity without role silos or commercial fees.
- Unified Campus Member Model: Single identity across the platform. Any member can publish project workspaces and submit applications under one verified account.
- Institutional (.edu) Verification Gate: Registration mandates an institutional university
.eduemail address. Sensitive marketplace actions (creating projects, sending invitations, applying, uploading resumes) require email confirmation. - Authoritative Go Backend Boundary: The Go REST API (
:8080) is the sole authority for authentication, authorization, business rules, transactional state machines, and public APIs. - Defense-in-Depth AI Subsystem: A containerized FastAPI AI service (
ai-api:8000) on an internal network executes ML, vector search, and ranking pipelines, secured viaX-Internal-AI-Secret. - Graceful Degradation Everywhere: All AI operations (semantic search, ranking, draft generation, recommendations, moderation, analytics) automatically fall back to deterministic SQL logic if the AI service is unreachable.
- Authoritative Non-Mutation: AI endpoints return advisory draft payloads and never mutate authoritative database tables directly.
- Self-Hosted IAM (SuperTokens Core): Session management, credential handling, and email verification run on-premise in Docker on port
3567. - Dedicated Vector Database (Qdrant): Dedicated Qdrant vector engine (
lynk-qdrant:6333) stores and indexes 384-dimensional dense vectors (all-MiniLM-L6-v2) acrosscampus_studentsandcampus_projectscollections using HNSW cosine distance search, isolating vector computation from relational workloads. - Dedicated Object Storage (MinIO S3): Student resumes are stored exclusively in MinIO S3 (
resumesbucket); PostgreSQL stores only object keys and file metadata. - Containerization Boundary: Go API, AI API, AI Worker, SuperTokens Core, PostgreSQL, and MinIO run in Docker Compose. The Next.js frontend runs on the host machine for instant Hot Module Replacement (HMR).
- Unified Control Plane: A root
Makefilestandardizes onboarding, dependency installation, and quality gates across Go, TypeScript, and Python.
+------------------------------------------------------------------------+
| HOST ENVIRONMENT (DEVELOPMENT) |
| |
| Next.js 16 (App Router + React 18.3 + TypeScript 5.6 + Tailwind 3.4) |
| URL: http://localhost:3000 |
| Auth: supertokens-web-js (Session, EmailPassword, EmailVerification) |
+------------------------------------------------------------------------+
| |
| 1. Authentication & Sessions | 2. Edge Requests (:8080)
| http://localhost:8080/api/v1| http://localhost:8080
v v
+------------------------------------------------------------------------+
| DOCKER COMPOSE NETWORK (lynk-net) |
| |
| +----------------------------------------------------------------+ |
| | Nginx Edge Gateway (Container: lynk-gateway, Port: 8080) | |
| | Least-conn proxy, 5s micro-cache, keepalive connection pooling| |
| +----------------------------------------------------------------+ |
| | |
| v |
| +----------------------------------------------------------------+ |
| | Go REST API Server (Container: lynk-api) | |
| | Authoritative business rules, session claims, circuit breaker | |
| +----+-------------------+-------------------+-------------------+ |
| | | | | |
| | SQL (:6432) | Cache (:6379) | Internal HTTP | |
| v v v (:8000) | |
| +-------------+ +-------------+ +-------------------+ | |
| | PgBouncer | | Redis 7 | | Gunicorn ASGI | | |
| | Transaction | | Rate limit, | | (lynk-ai-api:8000)| | |
| | Multiplex | | cache, bus | | 4 Uvicorn workers | | |
| +------+------+ +------+------+ +---------+---------+ | |
| | | | | |
| | +-------------+ | | |
| | | ARQ | Shared Disk | |
| v SQL v Task v (/data) | |
| +-------------------+ +--------------------+ | |
| | PostgreSQL 16 | | AI Worker Daemon | | |
| | Relational tables | | (lynk-ai-worker) | | |
| | Outbox & Audits | | Batch tasks & graph| | |
| +-------------------+ +----------+---------+ | |
| ^ | | |
| | IAM Auth | openCypher | |
| +------+------------+ v | |
| | SuperTokens Core | +--------------------+ | |
| | Container (:3567) | | Kuzu Columnar Graph| | |
| +-------------------+ | Persistent on disk | | |
| +--------------------+ | |
| | | |
| v HNSW | |
| +-------------------+ +--------------------+ | |
| | MinIO S3 Engine |<--------------| Qdrant Vector DB | | |
| | Resumes bucket | S3 Metadata | Dense embeddings | | |
| +-------------------+ +--------------------+ | |
+------------------------------------------------------------------------+
| Layer | Component | Description |
|---|---|---|
| Control Plane | Root Makefile |
Multi-language onboarding, Git hook installation, and unified test/lint gates |
| Gateway & Reverse Proxy | Nginx (lynk-gateway:8080) |
Port 8080 entrypoint, least_conn load balancing, keep-alive pooling (128), SSE bypass |
| Frontend | Next.js 16 (App Router) | React 18.3, TypeScript 5.6, Tailwind CSS 3.4, TanStack Query 5 (host-executed) |
| Authoritative Backend | Go 1.25+ | Chi router v5.3, pgx/v5, SuperTokens SDK, MinIO Go SDK, thread-safe Circuit Breaker |
| Caching & Rate Limiting | Redis 7 (lynk-redis:6379) |
120 req/min sliding-window limiter & cache-aside store for project feeds |
| Connection Pooling | PgBouncer (lynk-pgbouncer:6432) |
Transaction mode multiplexing 5,000 client connections onto 25-40 PostgreSQL backends |
| AI Microservice Runtime | Python 3.11 (lynk-ai-api:8000) |
Gunicorn multi-process ASGI server (4 Uvicorn workers) with worker recycling (max-requests: 5000) |
| AI Background Worker | Python 3.11 (lynk-ai-worker) |
Dedicated ARQ task worker executing asynchronous graph projections and batch embeddings |
| Graph Intelligence Engine | Kuzu Graph DB | Embedded columnar C++ graph engine with openCypher querying, persisted on /data/kuzu_campus_graph |
| Vector Search | Qdrant Engine (lynk-qdrant:6333) |
Dedicated 384-dimensional dense vector store with HNSW indexing and memory fallback |
| Message Broker & Event Bus | RabbitMQ 3.13 (lynk-rabbitmq:5672) |
AMQP event bus with dead-letter exchange for audit logging and background events |
| Full-Text Search Engine | Meilisearch 1.7 (lynk-meilisearch:7700) |
Instant typo-tolerant full-text search indexing campus projects |
| Database | PostgreSQL 16 | Relational application schema, SuperTokens IAM state, outbox events, and immutable audit logs |
| IAM & Auth | SuperTokens Core 9.3 | Self-hosted session management, EmailPassword, EmailVerification recipes |
| Object Storage | MinIO | S3-compatible object storage dedicated exclusively to student resumes (resumes bucket) |
| Orchestration | Docker Compose | Multi-container environment (Gateway, API, AI API, AI Worker, Qdrant, DB, IAM, MinIO, Redis) |
Lynk/
+-- Makefile # Universal developer control plane (setup, test, lint, format)
+-- docker-compose.yml # Postgres, Qdrant, MinIO, SuperTokens, Go API, AI API, AI Worker
+-- .env.example # Canonical environment variable template
+-- .pre-commit-config.yaml # Universal Git hook suite (Prettier, Ruff, Go fmt, whitespace)
+-- ai/ # FastAPI AI Backend & Async Workers
| +-- Dockerfile # Multi-stage Python 3.11 container build
| +-- requirements.txt # PyTorch, sentence-transformers, asyncpg, scikit-learn
| +-- app/ # FastAPI entrypoint, config, health probes, routers
| | +-- api/ # Internal routes (search, ranking, skills, jobs, analytics)
| | +-- middleware/ # X-Internal-AI-Secret, correlation tracing, run_tracker
| +-- models/embeddings/ # Singleton EmbeddingProvider & content hashing
| +-- pipelines/ # ML pipelines (search, ranking, moderation, reviews, forecasting)
| +-- llm/ # vLLM client abstraction, prompts, schemas
| +-- workers/ # SKIP LOCKED queue daemon & background handlers
| +-- evaluation/ # Offline IR metrics (NDCG, MRR, F1) & benchmark harness
| +-- tests/ # 166 pytest test cases across all AI subsystems
+-- backend/ # Authoritative Go REST API
| +-- Dockerfile # Multi-stage production container build
| +-- cmd/api/main.go # Dependency injection, router setup, server entrypoint
| +-- internal/
| | +-- ai/ # Go AI client, orchestrator, public handlers, project embeddings
| | +-- auth/ # SuperTokens SDK initialization & session claims
| | +-- user/ # Campus member profiles and resume handling
| | +-- project/ # Project workspace management & visibility
| | +-- team/ # Team members, role transitions, and invitations
| | +-- recruitment/ # Project applications and applicant review
| | +-- workspace/ # Modular section registries and external resources
| | +-- job/ # Job postings, filtering, and search (legacy)
| | +-- application/ # Proposal applications (legacy)
| | +-- contract/ # Deliverable contract state machine (legacy)
| | +-- review/ # Post-completion ratings and reviews
| | +-- storage/ # MinIO S3 client wrapper
| | +-- database/ # Connection pooling (pgxpool) and raw SQL migrator
| | +-- middleware/ # SuperTokens session auth, CORS, logging, recovery
| +-- migrations/ # Incremental SQL migration files (000001 - 000024)
+-- frontend/ # Next.js App Router frontend (runs on host)
| +-- src/
| | +-- app/ # App Router pages ((auth), projects, activity, profile)
| | +-- components/ # Reusable UI components, ProjectCard, TeamManagementModal
| | +-- lib/ # API client, SuperTokens helpers, project-api
| | +-- types/ # TypeScript interfaces matching backend models
+-- docs/ # Comprehensive documentation suite, API specs, and ERDs
+-- scripts/ # Automated smoke test suites (PowerShell and Bash)
You can set up the Lynk development environment using either the Root Makefile (recommended for automated multi-language bootstrapping) or manually via Individual CLI Commands.
- Docker and Docker Compose (v24+)
- Go (v1.22+, recommended: 1.25.x)
- Node.js (v20+) and npm
- Python (v3.11+)
- Git (v2.40+)
The top-level Makefile automates environment variable copying, Git hook installation, Go module verification, frontend dependencies, and Python virtual environment creation in a single command.
# Clone the repository
git clone https://github.com/BIJJUDAMA/Lynk.git
cd Lynk
# Initialize all dependencies and Git hooks
make setupThis single command:
- Creates
.envfrom.env.exampleif not already present. - Installs and activates Git pre-commit hooks via
pre-commit install. - Downloads and verifies backend Go modules in
backend/. - Installs frontend npm packages (
npm install) infrontend/. - Creates a Python virtual environment (
ai/.venv) and installsai/requirements.txt.
docker compose up -d --buildcd frontend
npm run devVisit http://localhost:3000 in your browser.
If you only need to bootstrap a specific subsystem:
make setup-hooks # Link pre-commit hooks into .git/hooks/pre-commit
make setup-go # Download and verify Go modules
make setup-frontend # Install npm packages in frontend/
make setup-ai # Create Python venv in ai/.venv and install dependenciesFollow these manual steps if you prefer direct command execution without make:
cp .env.example .envActivate local Git hooks so code formatting (Prettier, Ruff, Go fmt) runs automatically before each commit:
pre-commit installDownload and verify backend Go module dependencies:
cd backend
go mod download
go mod verify
cd ..Create a local virtual environment for the AI service and install requirements:
# Linux / macOS:
python3 -m venv ai/.venv
source ai/.venv/bin/activate
pip install -r ai/requirements.txt
deactivate
# Windows (PowerShell):
python -m venv ai\.venv
.\ai\.venv\Scripts\Activate.ps1
pip install -r ai\requirements.txt
deactivateLaunch PostgreSQL, SuperTokens Core, MinIO, Qdrant, Redis, RabbitMQ, Meilisearch, the Go REST API, FastAPI AI Backend, and the AI Worker:
docker compose up -d --buildVerify that all containers are healthy:
docker compose psService access registry:
- Go REST API (Authoritative):
http://localhost:8080 - FastAPI AI Backend (Internal):
http://localhost:8000 - SuperTokens Core IAM:
http://localhost:3567 - MinIO S3 API:
http://localhost:9000 - MinIO Web Console:
http://localhost:9001(User:minio_admin, Password:minio_password) - PostgreSQL 16:
localhost:5432(Database:lynk_db, User:lynk_user) - Qdrant Vector DB:
localhost:6333 - Meilisearch Full-Text:
localhost:7700 - RabbitMQ Management:
localhost:15672
Install dependencies and start the Next.js server on the host machine:
cd frontend
npm install
npm run devOpen http://localhost:3000 in your browser.
The root Makefile provides unified targets for cross-stack verification, linting, and formatting:
| Target | Description | Subsystems Executed |
|---|---|---|
make setup |
Complete onboarding (hooks, Go modules, npm dependencies, Python venv) | All |
make setup-hooks |
Installs Git pre-commit hook into .git/hooks/ |
Git |
make setup-go |
Downloads and verifies backend Go modules | Backend (backend/) |
make setup-frontend |
Installs npm dependencies | Frontend (frontend/) |
make setup-ai |
Creates Python venv and installs requirements | AI (ai/) |
make test |
Runs unit test suites across Go, frontend, and AI | All |
make lint |
Runs golangci-lint, oxlint, and ruff check |
All |
make format |
Auto-formats Go (gofmt), frontend (prettier), and Python (ruff) |
All |
make format-check |
Enforces formatting compliance (identical to CI) | All |
make load-test |
Runs complete 8-stage sequential k6 backend load test suite | Backend & Database |
make load-test-stress |
Runs Stage 5 high-concurrency stress test (1,000 VUs) | Backend & Database |
All public REST API endpoints are served by the authoritative Go API on port 8080 and prefixed with /api/v1.
| Domain | Method | Path | Auth Required | Description |
|---|---|---|---|---|
| Auth | POST | /auth/* |
Public | Handled by SuperTokens Core via mounted middleware |
| Profile | GET | /profile/me |
Session | Retrieve current campus member profile |
| Profile | PUT | /profile/me |
Session | Update bio, skills, department, graduation year |
| Profile | GET | /profile/recommendations |
Verified .edu | Intelligent profile completeness and skill advice |
| Resume | POST | /profile/resume |
Verified .edu | Upload resume PDF/DOCX to MinIO (5MB limit) |
| Resume | GET | /profile/resume |
Session | Download member resume via presigned S3 URL |
| Projects | GET | /projects |
Public | List and filter projects by category, skills, recruitment |
| Projects | POST | /projects |
Verified .edu | Create a new project workspace |
| Projects | GET | /projects/{slugOrId} |
Public | Detailed view of project workspace and sections |
| Projects | PATCH | /projects/{id} |
Lead / Maintainer | Update project title, description, category |
| Projects | PATCH | /projects/{id}/visibility |
Lead / Maintainer | Update visibility (public, unlisted, private) |
| Team | GET | /projects/{id}/members |
Public | List team members and assigned roles |
| Team | PATCH | /projects/{id}/members/{mId} |
Lead / Maintainer | Adjust member role (Lead, Maintainer, Member) |
| Team | DELETE | /projects/{id}/members/{mId} |
Lead / Maintainer | Remove member from project team roster |
| Team | POST | /projects/{id}/invitations |
Lead / Maintainer | Invite university student via institutional .edu email |
| Team | POST | /invitations/{id}/accept |
Verified .edu | Accept team invitation and join workspace |
| Sections | GET | /projects/{id}/sections |
Public | Retrieve ordered modular workspace sections |
| Sections | PUT | /projects/{id}/sections |
Lead / Maintainer | Update and re-order modular workspace sections |
| Resources | GET | /projects/{id}/resources |
Public | List external project resources and documentation links |
| Resources | POST | /projects/{id}/resources |
Lead / Maintainer | Add project documentation link or external resource |
| Resources | DELETE | /projects/{id}/resources/{rId} |
Lead / Maintainer | Delete external resource link |
| Recruitment | POST | /projects/{id}/applications |
Verified .edu | Submit project recruitment application with resume |
| Recruitment | GET | /projects/{id}/applications |
Lead / Maintainer | Review received applications and applicant notes |
| Recruitment | GET | /applications/me |
Session | List personal applications submitted by current user |
| Recruitment | PATCH | /applications/{id}/status |
Lead / Maintainer | Accept (adds to team roster), shortlist, or reject |
| Search | GET | /search/projects?q=... |
Public | Hybrid semantic + keyword project discovery |
| Search | GET | /search/people?q=... |
Verified .edu | Hybrid semantic + keyword student directory discovery |
| P2P Collaboration | POST | /projects/{id}/collaborators/match |
Verified .edu | Match complementary teammates covering missing project skills |
| P2P Collaboration | POST | /projects/{id}/collaborators/skill-gap |
Verified .edu | Evaluate student skill gap and learning pathway against project |
| P2P Collaboration | POST | /projects/{id}/assist |
Verified .edu | Natural language project creation & role synthesis via AI |
| Realtime Events | GET | /events/stream |
Session | Persistent Server-Sent Events (SSE) stream for live updates |
| Audit Logs | GET | /audit/logs |
Admin | Query immutable audit log trail across platform actions |
| Reviews | GET | /users/{id}/reviews |
Public | View aggregated bilateral peer ratings and reviews |
| AI Insights | GET | /users/{id}/ai-insights |
Public | Aspect breakdown (technical, timeliness, communication) |
| AI Analytics | GET | /analytics/skills |
Public | Campus skill demand metrics and statistical growth forecasts |
You can verify the entire monorepo using the root Makefile or through individual toolchain commands.
# Run all test suites across Go, Frontend, and Python AI
make test
# Run all linters (golangci-lint, oxlint, ruff check, typecheck)
make lint
# Check code formatting compliance (Go fmt, Prettier, Ruff)
make format-check
# Auto-format all code
make formatcd backend
go test -v -race -coverprofile=coverage.txt ./...
go vet ./...
# Run concurrency & race condition integration suite
go test -v -run TestConcurrency ./internal/...
# Run chaos fault-injection client tests
go test -v -run TestChaos ./internal/ai/client/...cd frontend
npm test # 101 unit & component tests
npm run typecheck # TypeScript strict type checking
npx playwright test # 11 End-to-End browser user journeys
npm run lint:ox
npm run format:check
npm run buildpython -m pytest ai/tests/ -v --cov=ai/app # 166 pytest cases
python -m ai.evaluation.harness # Offline IR NDCG benchmarks# 16-Phase End-to-End Stack Smoke Test (includes P2P endpoints & MinIO binary invariant):
bash scripts/smoke-test.sh
# Chaos & Fault-Injection Resilience Suite:
bash scripts/chaos-test.shLynk includes an automated, protocol-level load testing suite implemented in k6 to continuously validate system performance under ultra-concurrency campus traffic. For detailed architectural diagrams, capacity formulas, and complete latency distributions, see:
| Metric | Measured Value | Operational Context |
|---|---|---|
| Sustainable Throughput (Zone 1) | 2,042.3 req/s | Verified Green-Zone SLA with 11.4ms p95 latency and 0.00% errors |
| Saturation Ingestion Ceiling (Zone 2) | 3,193.4 req/s | Maximum server ingestion throughput before queueing latency inflection |
| Concurrent Connection Hold (Zone 3) | 20,000 VUs | Persistent keep-alive sockets sustained with 0.00% socket drops |
| DDoS Rate Limiting | 1.80ms drop | 120 req/min single-IP burst strictly blocked with HTTP 429 Too Many Requests |
| Real-World Campus Scale | ~20,400 to 30,600 users | Active campus students browsing with realistic 10s-15s browse/think time |
| Dynamic Autoscaling | 2 -> 6 Replicas | Proactive connection-aware scale-up with 5s sustained response window |
The consolidated benchmark suite (node tests/load/run_all.js or make load-test) executes 8 sequential load stages evaluating rate limiting, connection pooling, user breakpoint, saturation ceiling, and connection hold:
| Stage | Total Reqs | Throughput | p95 Latency | p99 Latency | Error Rate | Peak CPU | Peak RAM | Status |
|---|---|---|---|---|---|---|---|---|
| 01. Rate Limiting (DDoS Burst) | 300 | 30.0 req/s | 1.8ms | 3.3ms | 100.00% | 30.8% | 662 MB | PASS (Limiter Enforced) |
| 02. Cache & Read Benchmark | 7,131 | 177.1 req/s | 1.2ms | 2.2ms | 0.00% | 72.7% | 1,184 MB | PASS |
| 03. DB Pool Saturation | 6,351 | 157.9 req/s | 675us | 785us | 0.00% | 15.6% | 1,165 MB | PASS |
| 04. Max User Breakpoint | 4,866 | 48.5 req/s | 2.5ms | 4.0ms | 0.00% | 41.6% | 1,177 MB | PASS |
| 05. High-Concurrency Stress | 24,688 | 295.3 req/s | 2.0ms | 2.7ms | 0.00% | 87.4% | 1,217 MB | PASS (1,000 VUs) |
| 06. Ultra-Concurrency Stress | 119,744 | 1,464.1 req/s | 2.2ms | 3.5ms | 0.00% | 261.2% | 1,242 MB | PASS (2,500 VUs) |
| 07. Constant-Arrival Saturation | 335,340 | 3,193.4 req/s | 755.8ms | 1.01s | 0.00% | 611.8% | 1,908 MB | WARN (Latency High) |
| 08. Concurrent Connection Hold | 254,558 | 2,042.3 req/s | 11.4ms | 55.3ms | 0.00% | 368.2% | 1,648 MB | PASS (20,000 VUs) |
- Zone 1: Certified Sustainable Operating Capacity (Green Zone)
- Throughput:
2,042.3 req/sec| Latency SLA:p95 = 11.4ms| Error Rate:0.00% - Supported Campus Population: ~20,400 to 30,600 simultaneous active students (assuming 10s to 15s pause between clicks).
- Throughput:
- Zone 2: Saturation Ingestion Ceiling (Yellow Zone - Stress Limit)
- Ingestion Peak:
3,193.4 req/sec| Latency Profile:p95 = 755.8ms(Request queueing backpressure). - Operational Limit: Production workloads must remain below 50% of this ceiling (~1,600 req/s).
- Ingestion Peak:
- Zone 3: Connection Concurrency Limit
- Simultaneous Keep-Alive Sockets: 20,000 concurrent sockets sustained with zero drops.
| Tier | vCPU | RAM | Storage (NVMe SSD) | Campus Scale Supported |
|---|---|---|---|---|
| Recommended (Sweet Spot) | 8 vCPU | 16 GB - 32 GB | 250 GB - 500 GB | 20,000 - 40,000 students (sub-10ms latency, 50% CPU headroom) |
| Minimum Viable | 4 vCPU | 8 GB | 50 GB | Up to 15,000 students (~1,000 RPS sustained; stack uses ~3.8 GB RAM) |
# Run the complete 8-stage sequential load testing suite
make load-test
# Inspect real-time controller scaling logs during load
docker compose logs -f autoscaler
# Filter execution to an individual stage
node tests/load/run_all.js --stage=01_rate_limit
node tests/load/run_all.js --stage=06_ultra_concurrency_stress
node tests/load/run_all.js --stage=08_connection_hold- Strict .edu Validation: Registrations with non-.edu email domains are rejected immediately with HTTP 400.
- Email Verification Gate: Creating projects, inviting members, applying, uploading resumes, and generating AI drafts require confirmed institutional email ownership. Unverified attempts return HTTP 403 (
EMAIL_NOT_VERIFIED). - Authoritative Go Boundary: The Go backend is the sole authority for authentication, authorization, domain validation, and transactional state. FastAPI is strictly an internal compute engine.
- Defense-in-Depth AI Secret: The FastAPI AI backend requires
X-Internal-AI-Secreton all internal routes. It is never exposed directly to public web traffic. - Authoritative Non-Mutation: Generative AI endpoints return draft payloads and never mutate authoritative database rows directly.
- Graceful Degradation Everywhere: If the AI backend or GPU is unreachable, all Go endpoints seamlessly fall back to deterministic SQL logic with HTTP 200.
- Circuit Breaker Protection: The Go AI orchestrator trips after 5 consecutive failures for 30s, fast-bypassing to heuristics without blocking requests.
- Deterministic Database Migrations: All migrations in
backend/migrations/(000001through000024) are immutable and sequential. - Resumes in MinIO Exclusively: Resumes are never stored on local disk or inside PostgreSQL. All resume transfers stream directly through MinIO with short-lived presigned URLs for client downloads.
- Concurrency & Fairness: Candidate ranking excludes protected demographic attributes (gender, race, age, graduation year, ethnicity) for algorithmic fairness.