Quick Start Guide

🚀 Quick Start Guide

This guide will walk you through cloning, configuring, and booting the Criptofolio full-stack environment on your local machine.

📋 Prerequisites

Before getting started, ensure you have the following installed:

Node.js: v20.x or later (tested up to v24.x).
PNPM: v9.x or later (pnpm -v).
Git: For version control.

[!NOTE] Criptofolio operates on Node.js built-in node:sqlite support, eliminating external binary SQLite drivers for the OLTP ledger.

📥 1. Clone the Repository

Clone the repository to your local workspace:

git clone https://github.com/nelomr/criptofolio.git
cd criptofolio

📦 2. Install Monorepo Dependencies

Install all dependencies across the PNPM workspace packages from the root:

pnpm install

[!TIP] Criptofolio utilizes PNPM Catalogs defined in pnpm-workspace.yaml. Shared dependencies like TypeScript, Zod, and Hono share identical pinned versions across all packages.

⚙️ 3. Environment Configuration

Copy the example environment files for local development:

# Create root environment file
cp .env.example .env

# (Optional) Check frontend environment variables
cp apps/frontend/.env.example apps/frontend/.env

Key environment defaults:

Variable	Default Value	Description
`VITE_API_URL`	`http://localhost:3001`	URL where the Hono backend server listens
`VITE_APP_LANG`	`en`	Interface language (`en` or `es`)
`PORT`	`3001`	Port for the Hono backend HTTP service
`MOCK_MODE`	`false`	When `true`, uses an in-memory SQLite database
`CRIPTOFOLIO_DATA_DIR`	Workspace Root	Base path where `.db` and Parquet files are stored

💻 4. Launch the Development Servers

Criptofolio provides several development commands orchestrated by Turborepo:

Option A: Full-Stack (Recommended)

Spins up both the Vue 3 frontend (:5173) and the Hono backend (:3001) simultaneously:

pnpm dev:full

Option B: Frontend Only

If you want to work on the UI presentation layer while pointing to an existing backend or mock:

pnpm dev

Option C: Backend Only

Spins up the Hono API server with SQLite ledger and DuckDB analytical engine:

pnpm dev:backend

🌐 5. Access the Dashboard

Once the dev servers are running, open your browser and navigate to:

👉 http://localhost:5173

The backend API health check and metrics endpoints will be available at:

👉 http://localhost:3001/api/health

🧪 6. Running Tests & Typechecks

Before making changes, verify that the suite passes cleanly on your machine:

# Run unit & integration tests across all packages (Vitest)
pnpm test

# Statically check Vue and TypeScript types (vue-tsc)
pnpm typecheck

# Lint workspace files
pnpm lint

🧭 What’s Next?

Learn about Configuration & Environment
Understand the Hexagonal Architecture
Explore the FIFO Tax Engine