Skip to content
This repository was archived by the owner on Jul 6, 2026. It is now read-only.

README.md

Latest commit

 

History

History
220 lines (170 loc) · 10.9 KB

README.md

File metadata and controls

220 lines (170 loc) · 10.9 KB
Raw

🔁 Loopless

Intelligent Freelancer–Enterprise Collaboration Platform

Loopless connects freelancers and enterprises through semantic matching, real-time collaboration, async standups, and GitHub-integrated project transparency.

📌 Quick Links

Resource Link
📋 Project Plan docs/project-plan.md
📄 PRD docs/prd.md
🗓 Sprint Plan docs/sprint-plan.md
🏗 Tech Stack docs/tech-stack.md
🗄 Database Schema docs/database-schema.md
🔌 API Endpoints docs/api-endpoints.md
🎨 Wireframes docs/wireframes.md
⚔ Competitive Analysis docs/competitive-analysis.md
📊 Milestone Checklist docs/milestones.md

🧠 What is Loopless?

  • Semantic Matching — pgvector cosine similarity ranks freelancers/enterprises by relevance
  • GitHub Integration — Projects auto-sync commits from linked repos every 30 minutes
  • AI Project Summaries — RAG pipeline generates summaries from commits + files + links
  • Async Standups — Structured daily check-ins replace synchronous meetings
  • Real-time Messaging — SignalR-powered DMs with typing indicators and file sharing

🏗 Architecture

flowchart LR
    User((User))

    subgraph Edge[" "]
        direction TB
        Nginx[Nginx<br/>reverse proxy + TLS]
    end

    subgraph App[" Application "]
        direction TB
        FE[Next.js 15<br/>Frontend]
        BE[.NET 10 API<br/>Clean Architecture]
    end

    subgraph Data[" Data &amp; Messaging "]
        direction TB
        PG[(PostgreSQL 16<br/>+ pgvector)]
        Redis[(Redis 7<br/>cache + SignalR backplane)]
        MQ[[RabbitMQ 3]]
    end

    subgraph Identity[" Identity "]
        KC[Keycloak 25<br/>OAuth2 / OIDC]
    end

    subgraph External[" External "]
        direction TB
        OAI[OpenAI<br/>embeddings + chat]
        S3[(S3<br/>uploads)]
        GH[GitHub API]
    end

    subgraph Obs[" Observability &amp; Automation "]
        direction TB
        Prom[Prometheus<br/>+ Alertmanager]
        Graf[Grafana]
        Loki[Loki]
        ELK[Elastic + Logstash + Kibana]
        Kuma[Uptime Kuma]
        AIOps[AIOps triage<br/>Slack / Discord]
    end

    User --> Nginx
    Nginx -->|/| FE
    Nginx -->|/api, /hubs| BE
    FE <-->|REST + SignalR| BE

    BE --> PG
    BE --> Redis
    BE --> MQ
    BE --> KC
    BE --> OAI
    BE --> S3
    BE --> GH

    BE -.metrics.-> Prom
    BE -.logs.-> Loki
    BE -.logs.-> ELK
    Prom --> Graf
    Loki --> Graf
    Prom --> AIOps
    Kuma -.probes.-> BE
    Kuma -.probes.-> FE
    Kuma -.probes.-> KC

    classDef external fill:#f5f5f5,stroke:#999,stroke-dasharray:4 3,color:#333
    classDef obs fill:#fff7e6,stroke:#d4a373,color:#333
    class External external
    class Obs obs
Loading

Request path. Browser hits Nginx, which terminates TLS and routes / to the Next.js frontend and /api + /hubs to the .NET backend. The backend talks to Postgres (with pgvector for semantic search), Redis (cache + SignalR backplane for real-time messaging), and RabbitMQ (event bus). Authentication is delegated to Keycloak — the frontend redirects users there for login and the backend validates JWTs on every request.

Observability is a sidecar concern: Prometheus scrapes metrics, Loki and Logstash ingest logs from Serilog. Grafana visualizes both. Alertmanager forwards firing alerts to the AIOps triage service, which summarizes them via OpenAI and posts to Slack/Discord. Uptime Kuma runs black-box probes against the public surface.

Tech inventory

Layer Stack
Frontend Next.js 15, TypeScript, Tailwind v4, TanStack Query, Zustand, Framer Motion, SignalR client
Backend .NET 10, MediatR (CQRS), FluentValidation, EF Core 10 + Npgsql + pgvector, Hangfire, SignalR
Data PostgreSQL 16 (pgvector for embeddings), Redis 7, RabbitMQ 3
Identity Keycloak 25 — OAuth2/OIDC, GitHub SSO, realm imported from devops/keycloak/loopless-realm.json
AI OpenAI embeddings (1536-dim) + chat completions for project summaries / triage
Observability Prometheus 2.54 + Alertmanager, Grafana 11, Loki 3.1, Elasticsearch + Logstash + Kibana 8.14, Uptime Kuma
Automation aiops-triage (Node.js) — Alertmanager webhook → OpenAI → Slack/Discord; n8n for workflow automation
Infrastructure Docker Compose (dev), Kubernetes + Kustomize + Helm (prod — all infra via Helm), Nginx + Let's Encrypt
CI/CD GitHub Actions — lint/test/Trivy → push GHCR → kustomize deploy; release-please semantic versioning

🚀 Getting Started

git clone https://github.com/Loopless-Portal/LIFE-Group1.git
cd LIFE-Group1

# Copy env template and fill in secrets (Slack webhook, OpenAI key, etc.)
cp backend/.env.example .env

# Start the full dev stack
docker compose --profile core --profile observability --profile automation up -d

First start pulls images and installs NuGet/npm dependencies inside containers — budget 5-10 minutes. Subsequent starts are seconds.

Main local endpoints:

Service URL
Frontend http://localhost:3002
API (Swagger) http://localhost:8081/swagger
Nginx HTTPS proxy https://localhost
Keycloak http://localhost:8090
Grafana http://localhost:3011
Prometheus http://localhost:9090
Alertmanager http://localhost:9093
Kibana http://localhost:5601
Uptime Kuma http://localhost:3003
Loopless status page http://localhost:3003/status/loopless
Hangfire dashboard http://localhost:8081/hangfire
RabbitMQ management http://localhost:15672

⚙️ DevOps & Infrastructure

The stack is split across Docker Compose profiles so you can start only what you need. Profiles are additive — pass multiple --profile flags to combine them.

Profile Services When to use
core frontend, backend, postgres, redis, keycloak, rabbitmq, nginx, nginx-cert-generator App development — minimum runnable stack
observability prometheus, alertmanager, grafana, loki, node-exporter, postgres-exporter, elasticsearch, logstash, kibana, uptime-kuma Monitoring, logging, alerting, status pages
automation aiops-triage, n8n Alert routing → Slack/Discord, workflow automation
utility nginx-cert-generator Pulled in automatically by core; standalone for cert regen
production-ssl certbot (Let's Encrypt) Production only — pairs with nginx.prod.conf

Common commands:

# Full local stack
docker compose --profile core --profile observability --profile automation up -d

# Backend + DB only (fastest iteration loop)
docker compose --profile core up -d

# Provision Uptime Kuma monitors as code
bash devops/scripts/setup-uptime-kuma.sh

# Test the AIOps alert pipeline (Prometheus → Alertmanager → Slack/Discord)
bash devops/scripts/test-aiops-alert.sh

# Provision an Ubuntu production server (run on the server itself)
sudo -E SSH_PUBLIC_KEY='ssh-ed25519 ...' bash devops/scripts/server/bootstrap-ubuntu.sh

Infrastructure as code:

What Where How to apply
Helm charts devops/helm/ All infrastructure deployed via Helm
Kubernetes devops/k8s/ kubectl apply -k devops/k8s/overlays/staging
TLS certs devops/scripts/init-letsencrypt.sh DOMAIN=... EMAIL=... sudo bash ...
Secrets Azure Key Vault (KEYVAULT_URI env var) Backend auto-loads when URI is set

CI/CD workflows (.github/workflows/):

  • ci.yml — lint, test, build, Trivy scan, push images to GHCR
  • cd.yml — deploy to staging then production (manual approval gate)
  • release.yml — release-please semantic versioning

📅 Timeline

Sprint Dates Focus
Sprint 1 Mar 23 – Apr 3 Foundation & Product Definition
Sprint 2 Apr 6 – Apr 17 Frontend MVP
Sprint 3 Apr 20 – May 1 Backend Core
Sprint 4 May 4 – May 15 Backend Completion + DevOps Start
Sprint 5 May 18 – May 29 DevOps + Fullstack Integration
Sprint 6 Jun 1 – Jun 12 Analytics + Hardening + Presentation