VbloC Backend - Phase 1

A TypeScript Express API server with PostgreSQL database for the VbloC blogging platform.

Tech Stack

• Language: TypeScript
• Server: Express.js
• Database: PostgreSQL
• ORM: Prisma
• Validation: Zod
• Logging: Pino

Prerequisites

• Node.js (v18 or higher)
• PostgreSQL database
• npm or yarn

Setup

1. Install dependencies:

   npm install

2. Environment setup:

   cp .env.example .env

   Update the .env file with your database credentials and other configuration.

3. Database setup:

   # Run migrations
   npx prisma migrate dev
   
   # Generate Prisma client
   npx prisma generate

4. Start development server:

   npm run dev

Available Scripts

• npm run dev - Start development server with hot reload
• npm run build - Build for production
• npm start - Start production server
• npm run db:migrate - Run database migrations
• npm run db:generate - Generate Prisma client
• npm run db:studio - Open Prisma Studio

API Endpoints

Health & Info

• GET /api/health - Health check with database connectivity
• GET /api/version - Application version information
• GET /api - API information

Future Endpoints (Phase 2)

• /api/auth/* - Authentication endpoints
• /api/users/* - User management
• /api/posts/* - Blog post management

Project Structure

backend/
├── prisma/
│   ├── migrations/          # Database migrations
│   └── schema.prisma        # Database schema
├── src/
│   ├── controllers/         # Route handlers
│   ├── services/           # Business logic
│   ├── repos/              # Data access layer
│   ├── middlewares/        # Express middlewares
│   ├── utils/              # Utility functions
│   ├── db/                 # Database configuration
│   ├── types/              # TypeScript type definitions
│   ├── server.ts           # Express server setup
│   └── routes.ts           # Route definitions
├── .env                    # Environment variables (not in git)
├── .env.example           # Environment template
├── package.json
├── tsconfig.json
└── .gitignore

Environment Variables

Variable	Description	Default
DATABASE_URL	PostgreSQL connection string	-
PORT	Server port	4000
NODE_ENV	Environment mode	development
JWT_SECRET	JWT signing secret (Phase 2)	-
JWT_EXPIRES_IN	JWT expiration time (Phase 2)	7d
CORS_ORIGIN	Allowed CORS origin	http://localhost:3000

Database Schema

User Model

• id - Unique identifier (CUID)
• email - User email (unique)
• username - Username (unique)
• passwordHash - Hashed password
• role - User role (DEVELOPER | RECRUITER)
• createdAt - Creation timestamp
• updatedAt - Last update timestamp

Development

Adding New Endpoints

1. Create controller in src/controllers/
2. Add route in src/routes.ts
3. Add validation schemas using Zod
4. Update types in src/types/

Database Changes

1. Update prisma/schema.prisma
2. Run npx prisma migrate dev --name <migration_name>
3. Update TypeScript types if needed

Logging

The application uses Pino for structured logging:

• Request/response logging with unique request IDs
• Database connection status
• Error tracking with stack traces (development only)

Error Handling

• Global error handler catches all unhandled errors
• Standardized error response format
• Development vs production error details
• Request-specific error logging

Next Steps (Phase 2)

• JWT authentication implementation
• User registration and login
• Blog post CRUD operations
• Comment system
• File upload handling
• Advanced pagination
• Search functionality