Proyecto: Salesforce Admin Learning Platform (Plataforma Integral)
Equipo: VISIONARY ADMINS
Versión: 0.30.0 (Web Platform MVP)
Fecha: 17 Enero 2026
Tipo: Aplicación Web Full-Stack con Contenido Dinámico
Evolución del Proyecto:
Problema a Resolver: Crear una plataforma web integral que combine:
Objetivo del MVP (v0.30.0): Migrar la documentación estática a una aplicación web que:
Core Features:
Contenido:
Infraestructura:
| Rol | Responsabilidad | Persona |
|---|---|---|
| Product Owner | Visión del producto, priorización, validación | Wilmer (Usuario único) |
| AI Agent | Asume múltiples roles según fase (Tech Lead, Backend Dev, Frontend Dev, QA, DevOps, Code Reviewer) | Gemini AI |
| Developer/Implementador | Ejecuta código, prueba, reporta errores, valida funcionalidad | Wilmer (Usuario único) |
| Content Manager | Actualización de Markdown | Wilmer (Usuario único) |
| End Users | Estudiantes del curso | 5-10 miembros VISIONARY ADMINS |
| Fase | Duración | Entregables |
|---|---|---|
| Planificación | 1 día | SDLC, Roadmap, Task List, AI Role Framework |
| Análisis | 1 día | Requerimientos, User Stories |
| Diseño | 2 días | Arquitectura, DB Schema |
| Refactorización | 1 día | Nueva estructura de carpetas |
| Desarrollo Backend | 6 días | API, Auth, DB, Markdown Renderer |
| Desarrollo Frontend | 5 días | Templates, CSS, JavaScript |
| Integración | 2 días | Backend + Frontend + Contenido |
| Pruebas | 3 días | Unit, Integration, Manual |
| Deploy | 1 día | Render setup, migrations |
| Documentación | 1 día | API docs, User guide |
| TOTAL | ~24 días (4 semanas) | v0.30.0 en producción |
Nota: Timeline para desarrollo solo con AI Agent. Desarrollo paralelo de múltiples features no es posible.
Costo Total: $0 USD
| Recurso | Proveedor | Costo |
|---|---|---|
| Hosting Web | Render Free Tier | $0 |
| Database | PostgreSQL (Render) | $0 |
| Domain | Render subdomain | $0 |
| Git Hosting | GitHub | $0 |
| Desarrollo | Equipo (voluntario) | $0 |
Limitaciones Free Tier:
.md del repositorio y renderizarlos como HTML.Given que estoy autenticado
When navego a "Curriculum → Sprint 1 → Semana 1 → Clase 1 Teoría"
Then veo el contenido Markdown renderizado como HTML
And veo un sidebar con el índice de la clase
And veo breadcrumbs de navegación
And veo botones "Anterior" y "Siguiente"
Given que estoy viendo una clase
When marco el checkbox "Clase completada"
Then el sistema guarda mi progreso en la base de datos
And mi % de progreso del Sprint se actualiza
And el checkbox permanece marcado al recargar la página
Given que estoy en el dashboard
When veo la sección "Mi Progreso"
Then veo mi % de completitud del Sprint 1
And veo cuántas clases he completado
And veo cuántos Superbadges he terminado
And veo cuántos días quedan para el deadline
Given que estoy en el dashboard
When navego a la pestaña "Equipo"
Then veo una tabla con todos los miembros
And veo el % de progreso de cada uno
And veo mi posición en el ranking
And la tabla se actualiza automáticamente cada 30 segundos
Given que tengo acceso al repositorio
When edito un archivo Markdown y hago git push
Then la plataforma detecta el cambio (webhook o polling)
And actualiza el contenido automáticamente
And los usuarios ven el nuevo contenido sin necesidad de redeploy
┌─────────────────────────────────────────────────────────┐
│ USUARIOS (Web Browser) │
└────────────────────────┬────────────────────────────────┘
│ HTTPS
▼
┌─────────────────────────────────────────────────────────┐
│ RENDER WEB SERVICE │
│ ┌───────────────────────────────────────────────────┐ │
│ │ FASTAPI APPLICATION │ │
│ │ ┌─────────────────────────────────────────────┐ │ │
│ │ │ Routers │ │ │
│ │ │ ├─ /auth (login, register, logout) │ │ │
│ │ │ ├─ /docs (render markdown) │ │ │
│ │ │ ├─ /progress (track user progress) │ │ │
│ │ │ └─ /api (REST endpoints) │ │ │
│ │ └─────────────────────────────────────────────┘ │ │
│ │ ┌─────────────────────────────────────────────┐ │ │
│ │ │ Services (Business Logic) │ │ │
│ │ │ ├─ MarkdownRenderer │ │ │
│ │ │ ├─ AuthService │ │ │
│ │ │ └─ ProgressService │ │ │
│ │ └─────────────────────────────────────────────┘ │ │
│ │ ┌─────────────────────────────────────────────┐ │ │
│ │ │ Models (SQLAlchemy ORM) │ │ │
│ │ │ ├─ User │ │ │
│ │ │ ├─ Sprint │ │ │
│ │ │ ├─ Task │ │ │
│ │ │ └─ UserProgress │ │ │
│ │ └─────────────────────────────────────────────┘ │ │
│ │ ┌─────────────────────────────────────────────┐ │ │
│ │ │ Templates (Jinja2) │ │ │
│ │ │ ├─ base.html │ │ │
│ │ │ ├─ dashboard.html │ │ │
│ │ │ ├─ doc_viewer.html │ │ │
│ │ │ └─ team.html │ │ │
│ │ └─────────────────────────────────────────────┘ │ │
│ └───────────────────────────────────────────────────┘ │
└────────────────────────┬────────────────────────────────┘
│ SQL
▼
┌─────────────────────────────────────────────────────────┐
│ RENDER POSTGRESQL DATABASE │
│ ┌───────────────────────────────────────────────────┐ │
│ │ Tables: │ │
│ │ ├─ users │ │
│ │ ├─ sprints │ │
│ │ ├─ tasks │ │
│ │ └─ user_progress │ │
│ └───────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────┐
│ GITHUB REPOSITORY │
│ (Contenido Markdown - Source of Truth) │
│ ├─ curriculum/ │
│ ├─ Superbadges/ │
│ ├─ Practica_Financiera/ │
│ └─ Gestor_de_Versiones/ │
└────────────────────────┬────────────────────────────────┘
│ Git Pull / Webhook
▼
[FastAPI App]
-- users table
CREATE TABLE users (
id SERIAL PRIMARY KEY,
name VARCHAR(100) NOT NULL,
email VARCHAR(255) UNIQUE NOT NULL,
password_hash VARCHAR(255) NOT NULL,
team VARCHAR(50) DEFAULT 'VISIONARY ADMINS',
role VARCHAR(20) DEFAULT 'student', -- 'student', 'instructor', 'admin'
is_active BOOLEAN DEFAULT TRUE,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
last_login TIMESTAMP
);
-- sprints table
CREATE TABLE sprints (
id SERIAL PRIMARY KEY,
number INTEGER NOT NULL UNIQUE,
name VARCHAR(100) NOT NULL,
description TEXT,
start_date DATE NOT NULL,
end_date DATE NOT NULL,
is_active BOOLEAN DEFAULT FALSE,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
-- tasks table (auto-generated from Markdown structure)
CREATE TABLE tasks (
id SERIAL PRIMARY KEY,
sprint_id INTEGER REFERENCES sprints(id) ON DELETE CASCADE,
category VARCHAR(50) NOT NULL, -- 'Clase', 'Superbadge', 'Practica'
title VARCHAR(200) NOT NULL,
description TEXT,
markdown_path VARCHAR(500) NOT NULL, -- Path relativo al repo
order_index INTEGER DEFAULT 0,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
UNIQUE(sprint_id, markdown_path)
);
-- user_progress table
CREATE TABLE user_progress (
id SERIAL PRIMARY KEY,
user_id INTEGER REFERENCES users(id) ON DELETE CASCADE,
task_id INTEGER REFERENCES tasks(id) ON DELETE CASCADE,
status VARCHAR(20) DEFAULT 'not_started', -- 'not_started', 'in_progress', 'completed'
started_at TIMESTAMP,
completed_at TIMESTAMP,
notes TEXT,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
UNIQUE(user_id, task_id)
);
-- indexes for performance
CREATE INDEX idx_user_progress_user_id ON user_progress(user_id);
CREATE INDEX idx_user_progress_task_id ON user_progress(task_id);
CREATE INDEX idx_user_progress_status ON user_progress(status);
CREATE INDEX idx_tasks_sprint_id ON tasks(sprint_id);
CREATE INDEX idx_tasks_markdown_path ON tasks(markdown_path);
CREATE INDEX idx_users_email ON users(email);
POST /api/auth/register - Registrar nuevo usuario
POST /api/auth/login - Iniciar sesión (retorna JWT)
POST /api/auth/logout - Cerrar sesión
GET /api/auth/me - Obtener usuario actual
GET /docs/{path:path} - Renderizar Markdown dinámicamente
Ejemplo: /docs/curriculum/sprint_01/semana_01/01-clase_1_teoria
GET /api/progress/me - Progreso del usuario actual
GET /api/progress/team - Progreso de todo el equipo
POST /api/progress/task/{task_id}/mark - Marcar tarea (toggle status)
PATCH /api/progress/{id} - Actualizar notas de tarea
GET /api/sprints - Listar todos los sprints
GET /api/sprints/{id} - Obtener sprint específico
GET /api/sprints/{id}/tasks - Obtener tareas del sprint
GET /api/tasks/{id} - Obtener tarea específica
GET /api/users - Listar todos los usuarios
GET /api/users/{id} - Obtener usuario específico
PATCH /api/users/{id} - Actualizar usuario
DELETE /api/users/{id} - Desactivar usuario
salesforce_admin/
├── app/ # Aplicación FastAPI
│ ├── __init__.py
│ ├── main.py # Entry point
│ ├── config.py # Configuración (env vars)
│ ├── database.py # DB connection
│ ├── dependencies.py # Dependency injection
│ ├── models/ # SQLAlchemy models
│ │ ├── __init__.py
│ │ ├── user.py
│ │ ├── sprint.py
│ │ ├── task.py
│ │ └── progress.py
│ ├── schemas/ # Pydantic schemas
│ │ ├── __init__.py
│ │ ├── user.py
│ │ ├── sprint.py
│ │ ├── task.py
│ │ └── progress.py
│ ├── routers/ # API routes
│ │ ├── __init__.py
│ │ ├── auth.py
│ │ ├── docs.py # Markdown rendering
│ │ ├── progress.py
│ │ ├── sprints.py
│ │ └── users.py
│ ├── services/ # Business logic
│ │ ├── __init__.py
│ │ ├── auth_service.py
│ │ ├── markdown_service.py # Markdown → HTML
│ │ ├── progress_service.py
│ │ └── task_service.py
│ ├── middleware/
│ │ ├── __init__.py
│ │ ├── auth.py
│ │ ├── cors.py
│ │ └── logging.py
│ ├── templates/ # Jinja2 templates
│ │ ├── base.html
│ │ ├── components/
│ │ │ ├── navbar.html
│ │ │ ├── sidebar.html
│ │ │ └── breadcrumbs.html
│ │ ├── auth/
│ │ │ ├── login.html
│ │ │ └── register.html
│ │ ├── dashboard.html
│ │ ├── doc_viewer.html # Renderiza Markdown
│ │ └── team.html
│ └── static/ # Assets estáticos
│ ├── css/
│ │ ├── tailwind.css
│ │ └── custom.css
│ ├── js/
│ │ ├── alpine.js
│ │ └── app.js
│ └── images/
├── content/ # Contenido Markdown (sin cambios)
│ ├── curriculum/
│ ├── Superbadges/
│ ├── Practica_Financiera/
│ └── Gestor_de_Versiones/
├── tests/ # Tests
│ ├── __init__.py
│ ├── conftest.py
│ ├── test_auth.py
│ ├── test_markdown.py
│ ├── test_progress.py
│ └── test_api.py
├── alembic/ # DB migrations
│ ├── versions/
│ └── env.py
├── docs/ # Documentación del proyecto
│ ├── SDLC.md # Este documento
│ ├── DEVELOPMENT_RULES.md # Reglas de desarrollo
│ ├── ROADMAP.md # Roadmap del proyecto
│ ├── TASK_LIST.md # Lista de tareas
│ ├── IMPLEMENTATION_PLAN.md # Plan de implementación
│ ├── API.md # Documentación de API
│ └── DEPLOYMENT.md # Guía de deploy
├── scripts/ # Scripts de utilidad
│ ├── seed_data.py # Cargar datos iniciales
│ ├── sync_tasks.py # Sincronizar tareas desde Markdown
│ └── backup_db.py # Backup de base de datos
├── .env.example # Ejemplo de variables de entorno
├── .gitignore
├── requirements.txt # Dependencias Python
├── docker-compose.yml # Para desarrollo local
├── render.yaml # Configuración de Render
└── README.md # README principal
| Capa | Tecnología | Versión | Justificación |
|---|---|---|---|
| Backend | FastAPI | 0.109+ | Async, rápido, autodocumentación |
| ORM | SQLAlchemy | 2.0+ | ORM maduro, async support |
| Database | PostgreSQL | 15+ | Relacional, robusto |
| Auth | python-jose | 3.3+ | JWT tokens |
| Password | passlib[bcrypt] | 1.7+ | Bcrypt hashing |
| Markdown | python-markdown | 3.5+ | Markdown → HTML |
| Templates | Jinja2 | 3.1+ | Server-side rendering |
| JS Framework | Alpine.js | 3.13+ | Interactividad (3KB) |
| CSS | TailwindCSS | 3.4+ | Utility-first |
| Testing | pytest | 7.4+ | Unit & integration tests |
| Migrations | Alembic | 1.13+ | DB schema versioning |
| Deploy | Render | - | Free tier, auto-deploy |
# Imports ordenados (isort)
from typing import List, Optional
from fastapi import APIRouter, Depends
from sqlalchemy.orm import Session
from app.models.user import User
from app.schemas.user import UserCreate
from app.services.auth_service import AuthService
# Naming conventions
class UserService: # PascalCase para clases
def get_user_by_email(self): # snake_case para métodos
user_email = "test@example.com" # snake_case para variables
# Type hints obligatorios
def create_user(
user_data: UserCreate,
db: Session = Depends(get_db)
) -> User:
"""
Crea un nuevo usuario en el sistema.
Args:
user_data: Datos del usuario a crear
db: Sesión de base de datos
Returns:
User: Usuario creado
Raises:
ValueError: Si el email ya existe
"""
pass
# Constants en UPPER_CASE
MAX_LOGIN_ATTEMPTS = 5
DEFAULT_PAGE_SIZE = 20
feat(auth): add JWT token refresh endpoint
fix(markdown): correct relative link resolution
docs(api): update progress endpoints documentation
test(users): add unit tests for user service
refactor(models): simplify user_progress relationship
style(frontend): format templates with prettier
chore(deps): update fastapi to 0.109.0
main (production)
↑
develop (staging)
↑
feature/add-markdown-renderer
feature/implement-auth
hotfix/fix-login-error
## Descripción
[Descripción clara de los cambios]
## Tipo de cambio
- [ ] Bug fix
- [ ] Nueva feature
- [ ] Breaking change
- [ ] Documentación
## Checklist
- [ ] Tests agregados/actualizados
- [ ] Documentación actualizada
- [ ] Code review solicitado
- [ ] CI/CD pasa
/\
/ \ E2E Tests (5%)
/────\ - Playwright
/ \ - User flows críticos
/────────\
/ \ Integration Tests (20%)
/────────────\ - API endpoints
/ \- DB queries
/────────────────\
Unit Tests (75%)
- Services
- Models
- Utilities
Mínimo aceptable: 75% coverage
Objetivo: 85% coverage
pytest --cov=app --cov-report=html --cov-report=term
services:
- type: web
name: salesforce-admin-platform
env: python
buildCommand: |
pip install -r requirements.txt
alembic upgrade head
python scripts/seed_data.py
startCommand: uvicorn app.main:app --host 0.0.0.0 --port $PORT
envVars:
- key: DATABASE_URL
fromDatabase:
name: salesforce-admin-db
property: connectionString
- key: SECRET_KEY
generateValue: true
- key: ENVIRONMENT
value: production
databases:
- name: salesforce-admin-db
databaseName: salesforce_admin
user: admin
Métricas:
Herramientas:
| Métrica | Objetivo v0.30.0 |
|---|---|
| Adopción | 90% del equipo usa la plataforma |
| Engagement | Usuarios activos 4+ veces/semana |
| Performance | 95% requests < 500ms |
| Bugs | < 3 bugs críticos en primer mes |
| Satisfacción | NPS > 8/10 |
Documento creado por: Equipo VISIONARY ADMINS
Última actualización: 17 Enero 2026
Versión: 1.0