Flow Stack Server

A production-ready REST API built with TypeScript, Express 5, Prisma 7, and PostgreSQL using domain-driven modular architecture.

Features

• JWT dual-token authentication (access + refresh tokens via HttpOnly cookies)
• Role-based access control (USER, ADMIN)
• Task management with CRUD operations, filtering, search, and pagination
• Dashboard analytics with role-specific statistics
• User management for admin users
• Input validation with Zod schemas
• Standardized API responses across all endpoints

Prerequisites

• Node.js >= 20.x
• pnpm >= 11.x
• PostgreSQL database

Environment Variables

Create a .env file in the root directory:

NODE_ENV=development
DATABASE_URL=your_postgresql_database_url
PORT=8000
JWT_ACCESS_SECRET=your-access-token-secret
JWT_REFRESH_SECRET=your-refresh-token-secret
CLIENT_URL=http://localhost:3000

Variable Descriptions

Variable	Required	Default	Description
NODE_ENV	No	development	Environment mode (development, test, production)
DATABASE_URL	Yes	-	PostgreSQL connection string
PORT	No	8000	Server listening port
JWT_ACCESS_SECRET	Yes	-	Secret for signing access tokens
JWT_REFRESH_SECRET	Yes	-	Secret for signing refresh tokens
JWT_ACCESS_EXPIRES_IN	No	15m	Access token expiration
JWT_REFRESH_EXPIRES_IN	No	7d	Refresh token expiration
CLIENT_URL	Yes	-	Allowed CORS origin (must be a valid URL)

Getting Started

1. Install Dependencies

pnpm install

2. Set Up Database

# Generate Prisma client
pnpm prisma generate

# Run migrations
pnpm prisma migrate dev

# (Optional) Open Prisma Studio to view data
pnpm prisma studio

3. Start Development Server

pnpm dev

The server will start at http://localhost:8000.

4. Build for Production

pnpm build
pnpm start

Project Structure

flow-stack-server/
├── prisma/
│   ├── schema.prisma          # Root schema
│   └── models/                # Split model files
│       ├── user.prisma        # User, Account
│       └── task.prisma        # Task
├── src/
│   ├── index.ts               # Entry point
│   ├── mounted-routes.ts      # Route mounting
│   ├── config/                # Environment & Prisma
│   ├── types/                 # TypeScript types
│   └── modules/
│       ├── auth/              # Authentication
│       ├── user/              # User management (admin)
│       ├── task/              # Task management
│       ├── dashboard/         # Dashboard & analytics
│       └── shared/            # Shared utilities
├── ENDPOINTS.md               # API documentation
├── AGENTS.md                  # Architecture guide
└── README.md                  # This file

API Overview

Authentication

Method	Endpoint	Description
POST	/api/v1/auth/sign-up	Register new user
POST	/api/v1/auth/sign-in	Login
POST	/api/v1/auth/sign-out	Logout
POST	/api/v1/auth/refresh-token	Refresh tokens
GET	/api/v1/auth/profile	Get profile

Tasks

Method	Endpoint	Description
POST	/api/v1/tasks	Create task
GET	/api/v1/tasks	List tasks (filtered)
GET	/api/v1/tasks/:id	Get task
PATCH	/api/v1/tasks/:id	Update task
PATCH	/api/v1/tasks/:id/status	Update status
DELETE	/api/v1/tasks/:id	Delete task

Users (Admin)

Method	Endpoint	Description
GET	/api/v1/users	List all users
PATCH	/api/v1/users/:id/status	Toggle user active
DELETE	/api/v1/users/:id	Delete user

Dashboard

Method	Endpoint	Description
GET	/api/v1/dashboard/user	User dashboard
GET	/api/v1/dashboard/admin	Admin dashboard

For detailed API documentation, see ENDPOINTS.md.

Development

Scripts

pnpm dev          # Start dev server with hot reload
pnpm build        # Build for production
pnpm start        # Start production server

Architecture

This project follows Domain-Driven Modular Architecture with:

• Controller-Service separation (thin controllers, fat services)
• Shared module for cross-cutting concerns
• Zod validation for all inputs
• Standardized responses across all endpoints

For architecture details, see AGENTS.md.