Developer Portfolio — RESTful API

About • Technologies • Structure • Endpoints • Getting Started • Related Projects

Portfolio API is the backend that powers the personal developer portfolio. It exposes a RESTful API to serve projects, categories, technologies, and handles contact form submissions via email. Project detail content is stored as Markdown files served as static assets.

This codebase handles the Backend experience, developed in Node.js + TypeScript + Express + TypeORM + MySQL.

🔗 The frontend portfolio is available here.

📌 About

The API was built to fully decouple content management from the frontend. Projects, categories, and technologies are stored in a MySQL database and served via REST endpoints. Each project can have a rich Markdown file linked as its content, which the frontend renders dynamically, allowing updates to project documentation without touching the frontend code.

The contact endpoint uses Nodemailer with SMTP to forward messages directly to the developer's email.

🧪 Technologies

• Node.js
• TypeScript
• Express v5
• TypeORM
• MySQL (via mysql2)
• Nodemailer
• dotenv
• ts-node + nodemon

📁 Structure

src/
├── controllers/        # Express request handlers (projects, techs, categories, mail)
├── entity/             # TypeORM entities
├── migration/          # TypeORM database migration files
├── routes/             # Express route definitions
├── seeds/              # Database seed scripts
├── services/           # Business logic layer
├── data-source.ts      # TypeORM DataSource configuration
└── index.ts            # Application entry point
public/
└── files/              # Static files served at /files (project Markdown content, images)

🛣️ Endpoints

All routes are prefixed with /api.

Method	Route	Description
GET	/api/projects	List all projects (with categories and techs)
GET	/api/projects/:name	Get a single project by name
GET	/api/techs	List all technologies
GET	/api/categories	List all categories
POST	/api/contact	Send contact form email via SMTP

Static files (Markdown, images) are served directly at /files/*.

▶️ Getting Started

Requirements

• Node.js 18+
• MySQL database

Environment variables

Copy and configure the environment variables:

cp .env.example .env

# Database
DB_HOST=localhost
DB_PORT=3306
DB_USERNAME=
DB_PASSWORD=
DB_NAME=

# SMTP (contact form)
SMTP_USER=
SMTP_PASS=

# Server
PORT=3000

Running locally

# Clone the repository
git clone https://github.com/issagomesdev/portfolio-api.git
cd portfolio-api

# Install dependencies
npm install

# Run database migrations
npm run migration:run

# (Optional) Seed the database
npm run seed:run            # run all seeds
npm run seed:run:categories # seed categories only
npm run seed:run:techs      # seed techs only
npm run seed:run:projects   # seed projects only

# Start the development server
npm run dev

Build for production

npm run build
npm start

🔗 Related Projects

💻 Frontend (React + Vite) repository here