Joidy

Tu sistema personal de gestion del conocimiento con gamificacion.

Joidy es un monorepo Docker que combina:

• Frontend — Interfaz web construida con SvelteKit
• API — Backend REST con FastAPI
• AI Service — Embeddings y clasificacion con Gemini
• Worker — Tareas en background (sincronizacion con Obsidian, resumenes diarios)

---

Quick Start

Linux / macOS

make start

Windows

powershell -ExecutionPolicy Bypass -File start.ps1

Esto creara los directorios necesarios, configurara .env interactivamente e iniciara todos los servicios.

---

Prerrequisitos

Requisito	Notas
Docker	Instalar Docker Desktop
Docker Compose	Incluido en Docker Desktop

Verifica tu setup con:

• Linux/Mac: make doctor
• Windows: .\start.ps1 -Check

---

Configuracion

Variables Obligatorias

Edita el archivo .env despues de ejecutar el setup:

Variable	Descripcion	Como obtenerla
GEMINI_API_KEY	Clave para IA	Google AI Studio
OBSIDIAN_VAULT_PATH	Ruta absoluta a tu boveda de Obsidian	Ej: /home/usuario/Documents/Obsidian
SECRET_KEY	Clave de sesion (se genera automaticamente)	Se genera en primer setup

Variables Opcionales

# GitHub (sincronizacion)
GITHUB_TOKEN=
GITHUB_USERNAME=

# Telegram (notificaciones)
TELEGRAM_BOT_TOKEN=
TELEGRAM_ALLOWED_USER_ID=

---

Comandos

Linux / macOS (Makefile)

Comando	Descripcion
make start	Setup + iniciar servicios (modo interactivo)
make doctor	Verificar que todo este configurado correctamente
make dev	Iniciar servicios en modo desarrollo
make stop	Detener todos los servicios
make logs	Ver logs en tiempo real
make dev-reset	Reiniciar todo desde cero
make test	Ejecutar todos los tests
make migrate	Ejecutar migraciones de base de datos

Windows (PowerShell)

Script	Descripcion
.\start.ps1	Quick start interactivo
docker compose up -d	Iniciar servicios
docker compose down	Detener servicios

---

Acceso a la App

Servicio	URL
Web App	http://localhost:3000
API Docs	http://localhost:8000/docs
AI Service	http://localhost:8002

---

Solucion de Problemas

"Docker not found"

Asegurate de tener Docker Desktop instalado y ejecutandose.

"Port already in use"

Edita .env para cambiar los puertos:

FRONTEND_PORT=3001
API_PORT=8001

"La base de datos no inicia"

Ejecuta las migraciones:

make migrate

Verificar estado de servicios

make db-health

---

Estructura del Proyecto

.
├── api/              # FastAPI backend
├── ai-service/       # Servicio de IA (Gemini)
├── worker/           # Tareas background
├── frontend/         # SvelteKit web app
├── data/             # Datos (DB, uploads, vault)
├── docker-compose.yml
├── Makefile          # Comandos (Linux/Mac)
├── start.ps1         # Script (Windows)
└── .env              # Configuracion (no commits)

---

Contribuir

Las contribuciones son bienvenidas. Revisa la Guia de Contribucion para detalles sobre el flujo de trabajo, estandares de codigo y proceso de PR.

Busca issues etiquetados como good-first-issue para empezar.

---

Licencia

Distribuido bajo GNU General Public License v3.0. Ver LICENSE para mas informacion.

---

Creado por D4MAG3_WIZ4RD. Gracias a todos los contribuyentes y a la comunidad HackTheWorld-Team.