Skip to content

Commit be89b30

Browse files
frckbricefrckbrice
committed
Initial commit: Library Management REST API
- Complete REST API with Express.js and TypeScript - PostgreSQL database with Drizzle ORM - Role-based authentication (library_admin, super_admin) - Content management: libraries, stories, media, events, timelines - Moderation system with approval workflow - Email service with customizable templates - Analytics and dashboard features - Rate limiting and security middleware - Comprehensive README documentation
0 parents  commit be89b30

27 files changed

Lines changed: 13320 additions & 0 deletions

‎.env.example‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
DATABASE_URL=""
2+
SESSION_SECRET=""
3+
REPL_ID=""

‎.gitignore‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
node_modules
2+
dist
3+
4+
.env
5+
server/reset-db
6+
middleware/logger
7+
/logs

‎README.md‎

Lines changed: 293 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,293 @@
1+
# Library Management REST API
2+
3+
A comprehensive RESTful API backend for managing library content, resources, and operations. This system provides a robust platform for libraries to manage their collections, stories, media items, events, and user interactions through a well-structured API.
4+
5+
## Overview
6+
7+
This is a production-ready Node.js backend application built with Express.js, postgresql and TypeScript. It implements a complete content management system for libraries with role-based access control, content moderation, analytics tracking, and email communication capabilities.
8+
9+
## Technology Stack
10+
11+
- **Runtime**: Node.js with Express.js
12+
- **Language**: TypeScript
13+
- **Database**: PostgreSQL with Drizzle ORM
14+
- **Authentication**: Session-based authentication with bcrypt password hashing
15+
- **File Storage**: Cloudinary for image and media uploads
16+
- **Email Service**: Nodemailer for automated email responses
17+
- **Validation**: Zod for schema validation
18+
- **Rate Limiting**: Express-rate-limit for API protection
19+
- **Session Management**: Express-session with PostgreSQL or memory store
20+
21+
## Features
22+
23+
### Authentication & Authorization
24+
- Session-based user authentication
25+
- Role-based access control (library_admin, super_admin)
26+
- Secure password hashing with bcrypt
27+
- Session management with configurable stores
28+
29+
### Content Management
30+
- **Libraries**: Complete library profile management with location, description, images, and metadata
31+
- **Stories**: Rich text content management with featured images, tags, and approval workflow
32+
- **Timelines**: Interactive timeline creation associated with stories
33+
- **Media Items**: Image, video, and audio management organized into galleries
34+
- **Events**: Library event management with dates, locations, and images
35+
36+
### Moderation System
37+
- Content approval workflow for stories and media items
38+
- Super admin moderation capabilities
39+
- Featured content management
40+
- Publication status control
41+
42+
### Public API
43+
- Public endpoints for browsing libraries, stories, events, and media
44+
- Advanced search functionality
45+
- Filtering by tags, library, published status, and more
46+
- Pagination support
47+
48+
### Communication
49+
- Contact message system for visitor inquiries
50+
- Automated email response system with customizable templates
51+
- Email notification system
52+
53+
### Analytics & Reporting
54+
- View tracking and analytics collection
55+
- Admin dashboard with comprehensive statistics
56+
- Activity logging and monitoring
57+
58+
### Security & Performance
59+
- Rate limiting on all endpoints with different tiers
60+
- CORS configuration for cross-origin requests
61+
- Input validation and sanitization
62+
- Error handling middleware
63+
- Request logging
64+
65+
## Project Structure
66+
67+
```
68+
├── config/
69+
│ ├── bucket-storage/ # Cloudinary configuration
70+
│ ├── cors/ # CORS configuration
71+
│ └── database/ # Database schema, migrations, and seed data
72+
├── middlewares/
73+
│ ├── errors/ # Error handling middleware
74+
│ ├── logger.ts # Request logging
75+
│ └── rate-limiters.ts # Rate limiting configuration
76+
├── server/
77+
│ └── routes.ts # API route definitions
78+
├── services/
79+
│ ├── drizzle-services.ts # Database service layer
80+
│ └── email-service.ts # Email service implementation
81+
└── utils/
82+
└── validations.ts # Validation utilities
83+
```
84+
85+
## Installation
86+
87+
### Prerequisites
88+
- Node.js (v18 or higher)
89+
- PostgreSQL database
90+
- pnpm package manager (or npm/yarn)
91+
- Cloudinary account (for file uploads)
92+
- Email service credentials (Gmail or SMTP)
93+
94+
### Setup
95+
96+
1. Clone the repository:
97+
```bash
98+
git clone <repository-url>
99+
cd museumCall_backend
100+
```
101+
102+
2. Install dependencies:
103+
```bash
104+
pnpm install
105+
```
106+
107+
3. Configure environment variables:
108+
Create a `.env` file in the root directory with the following variables:
109+
110+
```env
111+
# Database
112+
DATABASE_URL=postgresql://user:password@localhost:5432/library_db
113+
DATAAPI_URL=your_neon_dataapi_url_if_using_neon
114+
115+
# Session
116+
SESSION_SECRET=your_session_secret_key
117+
118+
# Cloudinary
119+
CLOUDINARY_CLOUD_NAME=your_cloud_name
120+
CLOUDINARY_API_KEY=your_api_key
121+
CLOUDINARY_API_SECRET=your_api_secret
122+
123+
# Email (Gmail)
124+
GMAIL_USER=your_email@gmail.com
125+
GMAIL_PASS=your_app_password
126+
127+
# Server
128+
PORT=5500
129+
NODE_ENV=development
130+
131+
# CORS
132+
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:3001
133+
```
134+
135+
4. Set up the database:
136+
```bash
137+
# Generate database migrations
138+
pnpm db:generate
139+
140+
# Push schema to database
141+
pnpm db:push
142+
143+
# Seed the database with sample data
144+
pnpm db:seed
145+
```
146+
147+
5. Start the development server:
148+
```bash
149+
pnpm dev
150+
```
151+
152+
The server will start on `http://localhost:5500` (or the port specified in your `.env` file).
153+
154+
## API Endpoints
155+
156+
### Authentication
157+
- `POST /api/v1/auth/login` - User login
158+
- `GET /api/v1/auth/session` - Get current session
159+
- `POST /api/v1/auth/logout` - User logout
160+
161+
### Libraries
162+
- `GET /api/v1/libraries` - Get all libraries (public)
163+
- `GET /api/v1/libraries/:id` - Get library by ID (public)
164+
- `POST /api/v1/libraries` - Create library (super_admin only)
165+
- `PATCH /api/v1/libraries/:id` - Update library (admin)
166+
167+
### Stories
168+
- `GET /api/v1/stories` - Get all stories (public, supports filtering)
169+
- `GET /api/v1/stories/:id` - Get story by ID (public)
170+
- `GET /api/v1/stories/tags` - Get all story tags (public)
171+
- `POST /api/v1/admin/stories` - Create story (authenticated)
172+
- `PATCH /api/v1/admin/stories/:id` - Update story (authenticated)
173+
- `GET /api/v1/admin/stories/:id` - Get story for editing (authenticated)
174+
175+
### Timelines
176+
- `GET /api/v1/admin/stories/:id/timelines` - Get timelines for a story
177+
- `POST /api/v1/admin/stories/:id/timelines` - Create timeline for a story
178+
179+
### Media Items
180+
- `GET /api/v1/media-items` - Get all media items (public, supports filtering)
181+
- `GET /api/v1/media-items/:id` - Get media item by ID (public)
182+
- `POST /api/v1/media-items` - Upload media item (authenticated)
183+
- `PATCH /api/v1/media-items/:id` - Update media item (authenticated)
184+
185+
### Events
186+
- `GET /api/v1/events` - Get all events (public)
187+
- `POST /api/v1/events` - Create event (authenticated)
188+
- `PATCH /api/v1/events/:id` - Update event (authenticated)
189+
- `DELETE /api/v1/events/:id` - Delete event (authenticated)
190+
191+
### Contact Messages
192+
- `GET /api/v1/contact-messages` - Get contact messages (authenticated)
193+
- `POST /api/v1/contact-messages` - Submit contact message (public)
194+
- `PATCH /api/v1/contact-messages/:id` - Update message status
195+
- `POST /api/v1/contact-messages/:id/reply` - Send email response
196+
197+
### Super Admin
198+
- `GET /api/v1/superadmin/moderation/stories` - Get stories pending approval
199+
- `GET /api/v1/superadmin/moderation/media` - Get media pending approval
200+
- `PATCH /api/v1/superadmin/stories/:id/approve` - Approve story
201+
- `PATCH /api/v1/superadmin/stories/:id/reject` - Reject story
202+
- `GET /api/v1/superadmin/libraries` - Get all libraries
203+
- `GET /api/v1/superadmin/users` - Get all users
204+
- `POST /api/v1/superadmin/users` - Create user
205+
- `PATCH /api/v1/superadmin/users/:id` - Update user
206+
207+
### Admin Dashboard
208+
- `GET /api/v1/admin/dashboard/stats` - Get dashboard statistics
209+
- `GET /api/v1/admin/dashboard/analytics` - Get analytics data
210+
- `GET /api/v1/admin/dashboard/activity` - Get recent activity
211+
212+
### Utilities
213+
- `GET /api/v1/health` - Health check endpoint
214+
- `GET /api/v1/admin/galleries` - Get all galleries
215+
- `GET /api/v1/admin/media/tags` - Get all media tags
216+
217+
## Database Schema
218+
219+
The application uses PostgreSQL with the following main entities:
220+
221+
- **users**: User accounts with role-based access
222+
- **libraries**: Library profiles and information
223+
- **stories**: Content stories with rich text
224+
- **media_items**: Media files (images, videos, audio)
225+
- **timelines**: Timeline data associated with stories
226+
- **events**: Library events and programs
227+
- **contact_messages**: Visitor contact submissions
228+
- **analytics**: View and engagement tracking
229+
- **email_templates**: Customizable email templates
230+
- **message_responses**: Email response tracking
231+
232+
## Development
233+
234+
### Available Scripts
235+
236+
- `pnpm dev` - Start development server with hot reload
237+
- `pnpm build` - Build TypeScript to JavaScript
238+
- `pnpm start` - Start production server
239+
- `pnpm check` - Type check without emitting files
240+
- `pnpm lint` - Run ESLint
241+
- `pnpm test` - Run tests
242+
- `pnpm db:push` - Push schema changes to database
243+
- `pnpm db:generate` - Generate database migrations
244+
- `pnpm db:seed` - Seed database with sample data
245+
- `pnpm db:reset` - Reset database
246+
247+
### Code Quality
248+
249+
The project follows TypeScript best practices with:
250+
- Strict type checking
251+
- Consistent code formatting
252+
- Comprehensive error handling
253+
- Input validation using Zod schemas
254+
- RESTful API design principles
255+
256+
## Security Features
257+
258+
- Password hashing with bcrypt
259+
- Session-based authentication
260+
- Rate limiting on all endpoints
261+
- CORS protection
262+
- Input validation and sanitization
263+
- SQL injection prevention through ORM
264+
- Secure file upload handling
265+
266+
## Rate Limiting
267+
268+
The API implements different rate limiting tiers:
269+
- **Public endpoints**: Standard rate limits
270+
- **Admin endpoints**: Stricter rate limits
271+
- **Search endpoints**: Special rate limits for search operations
272+
- **Contact endpoints**: Dedicated rate limits for contact forms
273+
- **Email endpoints**: Rate limits for email sending
274+
275+
## Error Handling
276+
277+
The application includes comprehensive error handling:
278+
- Centralized error handler middleware
279+
- Consistent error response format
280+
- Detailed error logging
281+
- User-friendly error messages
282+
283+
## Contributing
284+
285+
This is a private project. For questions or issues, please contact the development team.
286+
287+
## License
288+
289+
MIT License
290+
291+
## Author
292+
293+
Developed as part of the Library Management System project.

0 commit comments

Comments
 (0)