convez.ai
Agente
vsvala

portfolio

vsvala/portfolio

Ver no GitHub
InicialPluginScore · de 0 a 100

Personal portfolio — built with Next.js 16, MUI, SQLite. Agentic coding exercise with Claude Code.

Instalação

$npx convez-ai vsvala/portfolio

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 2 meses
Versão
—
Issues abertas
1
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

Virva Svala — Portfolio

Live: https://virvasvala.vercel.app/

A personal portfolio website for software developer Virva Svala. Built with Next.js 16 App Router, Material UI, and SQLite — with a protected admin panel for managing all content without touching code.

This project is an agentic coding exercise. The entire codebase was developed using Claude Code (Anthropic's AI coding agent) through a structured multi-agent workflow. Different agents were assigned to different layers of the stack (data, UI, auth, upload, pages) and worked in parallel or in sequence according to a pre-defined implementation plan. See AGENTS.md for the agent roles and responsibilities.


Features

  • Bilingual (Finnish / English) — all content has _fi and _en variants; a language toggle cookie switches the active language across all server-rendered pages
  • Portfolio sections — Work experience, Projects, Education, Courses, Certifications — clickable cards with full detail views for work, projects, and education; Skills shown as a grid (no individual detail pages)
  • CV downloads — direct PDF download links for both Finnish and English CVs from the hero section
  • Profile photo — circular avatar in the hero section
  • Anchor sidebar — desktop-only left-column navigation with smooth-scroll links to all homepage sections
  • Online CV — print-optimised /cv page with all content from the database; print or save as PDF via browser
  • PDF attachments — work certificates and study certificates can be attached to individual entries and downloaded from their detail pages
  • Certifications section — static credential cards (images, issuer, year, technologies) shown as a homepage section (data in lib/static-content.ts; no separate /certifications page)
  • Feedback form — collapsible "anything unclear?" form on every detail page; submissions visible in admin at /admin/feedback
  • Recommendations — admin-managed recommendations/testimonials shown publicly
  • Protected admin panel — add, edit, and delete all content at /admin without touching code or redeploying; covers Work, Projects, Education, Courses, Skills, and Recommendations
  • File upload — PDF documents uploaded through the admin panel are stored in public/documents/ and linked to content entries
  • Responsive — mobile-first layout with a hamburger menu on small screens

Tech Stack

LayerTechnologyNotes
FrameworkNext.js 16.2.9 (App Router)Uses proxy.ts instead of middleware.ts; dynamic params are Promises
UIMaterial UI v9AppRouterCacheProvider for SSR emotion fix; all layout props via sx={{}}
DatabaseTurso (libSQL / SQLite)@libsql/client; local dev also works with SQLite via same client
Authjose (JWT)HS256, 7-day session cookie; single admin password
ValidationZodAll Server Action inputs validated before hitting the DB
FormsReact 19 useActionStateProgressive enhancement; no separate form library
LanguageTypeScript (strict)
Deploy targetVercel + TursoServerless functions on Vercel, database on Turso (EU West)

Project Structure

portfolio/
├── proxy.ts                        # Auth middleware for /admin/* routes
├── app/
│   ├── layout.tsx                  # Root layout — MuiProvider only
│   ├── (public)/                   # Route group: public pages with Nav + Footer
│   │   ├── layout.tsx
│   │   ├── page.tsx                # Homepage: Hero + Skills + section previews
│   │   ├── work/[id]/page.tsx
│   │   ├── projects/[id]/page.tsx
│   │   ├── education/[id]/page.tsx
│   │   ├── courses/page.tsx
│   │   └── recommendations/page.tsx
│   ├── admin/                      # Protected admin panel
│   │   ├── layout.tsx              # AdminNav only (no public Nav)
│   │   ├── login/page.tsx
│   │   ├── page.tsx                # Dashboard with content counts
│   │   ├── work/                   # List · New · Edit
│   │   ├── projects/
│   │   ├── education/
│   │   ├── courses/
│   │   ├── skills/
│   │   └── recommendations/
│   └── api/upload/route.ts         # PDF upload endpoint
├── components/
│   ├── providers/MuiProvider.tsx   # SSR emotion + ThemeProvider
│   ├── public/                     # Nav, Footer, HeroSection, cards, SkillsSection, CertificationsSection
│   ├── admin/                      # AdminNav, *Form.tsx for all types, DeleteButton
│   └── ui/
│       ├── LinkButton.tsx          # 'use client' wrapper for MUI Button + Next.js Link
│       └── ReadMoreChip.tsx        # Expandable "read more" chip component
├── lib/
│   ├── db/
│   │   ├── index.ts                # Turso/libSQL client (TURSO_URL + TURSO_AUTH_TOKEN)
│   │   ├── schema.sql              # Table definitions
│   │   ├── utils.ts                # toArgs() helper — converts object to libSQL named params
│   │   └── queries/                # work.ts · projects.ts · education.ts · courses.ts · skills.ts · recommendations.ts · documents.ts · feedback.ts
│   ├── hooks/useAdminForm.ts       # Shared hook for admin form state + redirect on success
│   ├── action-utils.ts             # validationError() — normalises Zod errors to ActionState
│   ├── zod-fields.ts               # Shared Zod field definitions (technologiesField, etc.)
│   ├── static-content.ts           # Static certifications data (images, credential URLs)
│   ├── utils.ts                    # parseTechnologies() — JSON array string → string[]
│   ├── session.ts                  # JWT encrypt / decrypt
│   ├── auth.ts                     # getSession(), requireAdmin()
│   ├── types.ts                    # Shared TypeScript interfaces
│   └── mui-theme.ts                # MUI theme (primary #1a1a2e, accent #e94560)
├── actions/                        # Server Actions: auth · work · projects · education · courses · skills · recommendations
├── tests/
│   ├── e2e/                        # Playwright end-to-end tests (80 tests across 12 spec files)
│   └── unit/                       # Vitest unit tests for pure helper functions
└── public/documents/               # Uploaded PDFs served as static files

Getting Started

Prerequisites

  • Node.js 20+
  • npm

Installation

git clone https://github.com/vsvala/portfolio.git
cd portfolio
npm install

Environment Variables

Create .env.local in the project root:

SESSION_SECRET=<base64-encoded-32-byte-key>
ADMIN_PASSWORD=<your-admin-password>
TURSO_URL=libsql://<your-db>.turso.io
TURSO_AUTH_TOKEN=<your-turso-token>

Generate a session secret:

node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

Run Locally

npm run dev

Open http://localhost:3000.

Build

npm run build   # TypeScript check + production build
npm run start   # Serve the production build

Admin Panel

Navigate to http://localhost:3000/admin/login and enter the password from .env.local.

From the dashboard you can:

  • Add / edit / delete work experience entries
  • Add / edit / delete projects
  • Add / edit / delete education entries
  • Add / edit / delete courses
  • Add / edit / delete skills
  • Add / edit / delete recommendations
  • Upload PDF documents (CV, work certificates, study certificates) and attach them to content entries

Deployment (Vercel + Turso)

1 — Create a Turso database

# Install Turso CLI
curl -sSfL https://get.tur.so/install.sh | bash

# Login and create database
turso auth login
turso db create portfolio

# Apply schema
turso db shell portfolio < lib/db/schema.sql

# Get credentials
turso db show portfolio --url      # → TURSO_URL
turso db tokens create portfolio   # → TURSO_AUTH_TOKEN

Seed initial data:

node scripts/seed-turso.mjs

2 — Deploy to Vercel

npx vercel --prod

3 — Add environment variables in Vercel

In the Vercel dashboard → Settings → Environment Variables, add all four variables for the Production environment:

VariableValue
TURSO_URLlibsql://portfolio-<name>.turso.io
TURSO_AUTH_TOKENtoken from turso db tokens create
SESSION_SECRETbase64 32-byte key
ADMIN_PASSWORDyour admin password
CERTIFICATE_PASSWORDpassword for /api/protected-doc (protects private-documents/)
RESEND_API_KEYResend API key (optional — enables the contact form)

Redeploy after adding variables.


CV PDFs

Place the CV files in public/documents/ for the download buttons in the hero section to work:

public/documents/cv_26_virva_svala_fi.pdf
public/documents/cv_26_virva_svala_en.pdf

Agentic Development Workflow

This project was built as a hands-on exercise in agentic software development using Claude Code. The implementation followed a structured multi-agent plan:

PhaseAgentsWhat was built
1 — FoundationSingle agent (sequential)Dependencies, .env.local, types, DB schema, session, auth, proxy
2 — Core layers4 agents in parallelData queries, Server Actions, UI components, file upload
3 — Public pagesPages AgentHomepage, list pages, detail pages
4 — Admin UIPages AgentLogin, dashboard, CRUD forms for all content types
5 — PolishReviewer AgentBuild fixes, TypeScript errors, runtime bug fixes, CLAUDE.md
6 — TestingTest Agent80 Playwright E2E tests + 20 Vitest unit tests in tests/
7 — RefactorCode Quality AgentShared action utils, Zod field helpers, DB utils, useAdminForm hook

Each agent received a scoped task with clear input/output contracts. Shared knowledge (breaking API changes, MUI constraints, security rules) was captured in CLAUDE.md and AGENTS.md so that every agent — and every future Claude Code session — starts with the same context.

Notable issues discovered during development and now documented for future agents:

  • Next.js 16 uses proxy.ts instead of middleware.ts; dynamic params and searchParams are Promises
  • MUI v9 does not accept layout props (gap, justifyContent, flexWrap) directly on Stack — they must go in sx={{}}
  • React 19 / Next.js 16 forbids passing functions (like Link) as props across the Server/Client boundary — solved with a LinkButton client wrapper and 'use client' card components
  • proxy.ts matcher must explicitly skip /admin/login to avoid an infinite redirect loop
  • Zod optional FK fields need .default(null) to avoid better-sqlite3 "Missing named parameter" errors

Testing

Tests live in the main repo under tests/:

npm test               # run all E2E tests (Playwright — starts own server on :3001 with local test.db)
npm run test:ui        # interactive Playwright UI mode
npm run test:unit      # run unit tests (Vitest, no server needed)

npm test spins up a dedicated Next.js server on port 3001 backed by a local SQLite test.db — production Turso data is never touched. The test DB is created fresh on every run (seeded in tests/e2e/seed-test-db.ts). Stop any existing server on port 3001 before running tests.

E2E coverage (80 tests across 12 spec files):

FileWhat it covers
smoke.spec.tsAll public routes return HTTP 200; 404 for unknown routes
navigation.spec.tsNav links, GitHub icon, language toggle FI↔EN, logo
homepage.spec.tsHero, CV buttons, anchor sidebar, section IDs, card links
admin.spec.tsAuth redirect, login form, wrong password, successful login, dashboard
feedback.spec.tsFeedback button and form on work, projects, and education detail pages
work.spec.tsWork list and detail pages, admin CRUD
projects.spec.tsProjects list and detail pages, admin CRUD
education.spec.tsEducation list and detail pages, admin CRUD
courses.spec.tsCourses public page, education detail with courses, admin CRUD
skills.spec.tsSkills section on homepage and CV, admin CRUD
recommendations.spec.tsRecommendations public page, admin CRUD
cv.spec.ts/cv page: all sections, print button, bilingual content

Unit tests (20 tests across 3 files):

FileWhat it covers
utils.test.tsparseTechnologies — JSON parse and error cases
zod-fields.test.tstechnologiesField — CSV and JSON array transforms
db-utils.test.tstoArgs — object-to-named-params conversion

Enabling the Contact Form

The contact form (/contact) is built and ready but disabled until a Resend API key is configured.

Steps to enable:

  1. Create a free account at resend.com
  2. Copy your API key and add it to .env.local:
    RESEND_API_KEY=re_xxxxxxxxxxxx
    
  3. Open app/(public)/contact/page.tsx and uncomment the form block (the {/* Contact form — disabled ... */} section)
  4. Restart the dev server — the form will appear on the right side of the Contact page

Production note: The from address in actions/contact.ts uses onboarding@resend.dev (Resend's sandbox sender). For production, verify your own domain in the Resend dashboard and update the from field to e.g. Portfolio <noreply@yourdomain.com>.


Roadmap (V2+)

  • Dark mode toggle
  • Contact form (Resend API) — implemented, enable by adding RESEND_API_KEY
  • Certifications homepage section — static credential cards (lib/static-content.ts); standalone /certifications page is not yet built
  • Courses section — DB-driven list on /courses and linked from education detail pages
  • Recommendations — admin-managed testimonials on /recommendations
  • GitHub integration — pinned repos pulled from the GitHub API
  • Feedback / "Suggest edit" form on detail pages — collapsible form, admin inbox at /admin/feedback
  • RAG chat — portfolio bot powered by Claude API + sqlite-vec embeddings
  • Dynamic CV print view — /cv page with @media print, always up to date from database
  • Privacy-friendly analytics (Plausible / Umami)

License

Personal portfolio — not intended for reuse as a template.

Ver o original no GitHub

Bom para

Relacionados