🏗️ A modern GraphQL API server - showcasing best practices for building scalable and maintainable GraphQL services 🏗️
- ✨ Features
- 🛠️ Technology Stack
- 🏗️ Architecture
- 📁 Project Structure
- 📝 GraphQL Schema
- 🚀 Getting Started
- 💻 Development
- 🗄️ Database Management
- 🏭 Production Deployment
- 🐳 Docker Deployment
- 📚 API Documentation
- 📄 License
- 🔮 GraphQL API: Robust GraphQL support with type checking powered by Apollo Server
- 📝 TypeScript: Fully typed codebase for improved developer experience and code quality
- 🔐 Authentication & Authorization: JWT-based authentication with role-based permissions
- 🗃️ Database Integration: PostgreSQL database with Prisma ORM for type-safe queries
- ⚡ Caching: Redis-based caching for improved performance
- 📦 Docker Support: Containerized deployment for consistent environments
- 🧩 GraphQL Directives: Custom directives for authentication and authorization control
- 📈 Scalable Architecture: Service-based architecture for maintainability and scalability
| Technology | Description |
|---|---|
| Node.js | JavaScript runtime environment |
| TypeScript | Typed JavaScript for better tooling |
| Apollo Server | GraphQL server implementation |
| Prisma | Next-generation TypeScript ORM |
| PostgreSQL | Powerful open-source relational database |
| Redis | In-memory data structure store for caching |
| Docker | Containerization platform |
| JWT | JSON Web Token for authentication |
This API follows a layered architecture approach:
Client Request → GraphQL API → Resolvers → Services → Data Access (Prisma) → Database
- 📊 GraphQL Layer: Handles incoming requests and response formatting
- 🔄 Resolver Layer: Maps GraphQL operations to service functions
- 🧠 Service Layer: Contains business logic and calls data access methods
- 💾 Data Access Layer: Interacts with the database via Prisma
graphql/
├── docker-compose.yml # Docker compose configuration
├── Dockerfile # Docker configuration
├── prisma/ # Prisma ORM configurations
│ ├── schema.prisma # Database schema
│ └── migrations/ # Database migrations
├── src/
│ ├── graphql/ # GraphQL schemas and resolvers
│ │ ├── directives/ # Custom GraphQL directives
│ │ ├── resolvers/ # GraphQL resolvers
│ │ └── schemas/ # GraphQL type definitions
│ ├── models/ # Database client models
│ │ ├── prisma.client.ts # Prisma client
│ │ └── redis.client.ts # Redis client
│ ├── services/ # Business logic services
│ └── types/ # TypeScript type definitions
└── ...
The GraphQL API provides the following core types and operations:
# User type
type User {
id: ID!
firstName: String!
lastName: String!
email: String!
password: String!
permission: Int!
createdAt: String!
updatedAt: String!
}
# Authentication response type
type AuthenticationResponse {
token: String
}
# Custom directives
directive @hasPermission(permission: Int!) on FIELD_DEFINITION
directive @authenticated on FIELD_DEFINITIONtype Query {
currentUser: User @authenticated # Returns the currently logged-in user
}type Mutation {
createUser(input: CreateUserInput!): CreateUserResponse! # Creates a new user
authentication(input: AuthenticationInput!): AuthenticationResponse! # Logs in a user and returns a token
}
input CreateUserInput {
firstName: String!
lastName: String!
email: String!
password: String!
}
input AuthenticationInput {
email: String!
password: String!
}- Node.js 18+ (Download)
- PNPM 10+ (Installation)
- PostgreSQL (Download)
- Redis (optional, for caching) (Download)
- Docker & Docker Compose (optional, for containerization) (Download)
-
Clone the repository:
git clone https://github.com/Xjectro/graphql-apollo-server cd graphql-apollo-server -
Install dependencies:
pnpm install
-
Generate Prisma client:
pnpm db:generate
Create a .env file in the root directory:
# Database
DATABASE_URL="postgresql://username:password@localhost:5432/database_name?schema=public"
# Authentication
JWT_SECRET="your-secure-jwt-secret"
JWT_EXPIRES_IN="24h"
# Redis (Optional - for caching)
REDIS_URL="redis://localhost:6379"
ENABLE_CACHE=true
# Server
PORT=4000
NODE_ENV=developmentRun the development server:
pnpm devThe GraphQL playground will be available at: http://localhost:4000/graphql
This project uses Prisma for database management. Available commands:
# Create and apply migrations based on schema changes
pnpm db:migrate
# Apply existing migrations to the database
pnpm db:deploy
# Check migration status
pnpm db:status
# Regenerate Prisma client
pnpm db:generate
# Reset database (caution: deletes all data)
pnpm db:reset
# Push schema changes without migrations (for development)
pnpm db:pushBuild and start the production server:
pnpm build
pnpm startBuild and run with Docker Compose:
# Start all services
pnpm docker
# Stop all services
pnpm docker:stop
# View logs
pnpm docker:logsThe Docker setup includes:
- GraphQL API server
- PostgreSQL database
- Redis cache
When the server is running, you can access the GraphQL Playground at http://localhost:4000/graphql, which provides:
- Interactive query builder
- Schema documentation
- Real-time testing of queries and mutations
mutation {
signUp(
input: {
firstName: "John"
lastName: "Doe"
email: "john.doe@example.com"
password: "securePassword123"
}
) {
id
firstName
lastName
email
}
}mutation {
signIn(
input: { email: "john.doe@example.com", password: "securePassword123" }
) {
token
}
}query {
currentUser {
id
firstName
lastName
email
}
}🔐 Note: To use the
currentUserquery, you need to send a token in your HTTP headers asAuthorization: Bearer <token>.
This project is licensed under the MIT License - see the LICENSE file for details.