5. Database Design (PostgreSQL with Prisma)

• Key Entities (Conceptual):

* User: id, email, passwordHash, firstName, lastName, role, createdAt, updatedAt

* Project: id, name, description, ownerId (FK to User), createdAt, updatedAt

* Task: id, title, description, status, projectId (FK to Project), assignedToId (FK to User), dueDate, createdAt, updatedAt

* Comment: id, content, taskId (FK to Task), authorId (FK to User), createdAt

* ... (add other relevant entities for your specific application)

• Relationships:

* User 1:N Projects (User can own multiple projects)

* Project 1:N Tasks (Project can have multiple tasks)

* User 1:N Tasks (User can be assigned multiple tasks)

* Task 1:N Comments (Task can have multiple comments)

* User 1:N Comments (User can write multiple comments)

• Indexing Considerations:

* id columns (primary keys) are automatically indexed.

* Foreign key columns (ownerId, projectId, assignedToId, authorId, etc.) should be indexed for efficient join operations.

* Columns frequently used in WHERE clauses (e.g., email for login, status for filtering tasks) should be considered for indexing.

• ORM/ODM Choice: Prisma (as mentioned in Core Technologies).

* Migrations: Prisma Migrate will be used to manage schema changes and apply them to the database in a controlled manner.

6. Authentication & Authorization

• Authentication Flow (JWT):

1. Registration: User provides email/username and password. Backend hashes password (e.g., bcrypt) and stores user in DB.

2. Login: User provides credentials. Backend verifies password, generates a short-lived Access Token and a longer-lived Refresh Token.

3. Token Storage: Frontend stores Access Token in memory (or secure HTTP-only cookie) and Refresh Token in an HTTP-only secure cookie (more secure against XSS).

4. Protected Routes: Access Token is sent with every subsequent request in the Authorization header (Bearer <token>). Backend verifies the token's signature and expiration.

5. Token Refresh: When Access Token expires, frontend uses Refresh Token to request a new Access Token from a dedicated /refresh endpoint.

6. Logout: Backend invalidates Refresh Token, frontend removes all tokens.

• Authorization Strategy (Role-Based Access Control - RBAC):

* Roles: Define distinct roles (e.g., Admin, Manager, Member, Guest).

* Permissions: Associate specific permissions with roles (e.g., Admin can manage_users, Manager can edit_all_projects, Member can edit_own_tasks).

* Middleware: Implement authorization middleware on the backend to check the user's role/permissions before allowing access to specific routes or resources.

• Security Considerations:

* Password Hashing: Use strong, slow hashing algorithms (e.g., bcrypt) with appropriate salt rounds.

* HTTPS: Enforce SSL/TLS for all communication.

* Input Validation: Strict validation on all user inputs (frontend and backend).

* CORS: Properly configure Cross-Origin Resource Sharing.

* Environment Variables: Store sensitive information (database credentials, API keys, JWT secrets) in environment variables.

* Rate Limiting: Protect against brute-force attacks on login/registration.

7. Deployment Strategy (AWS, Docker, CI/CD)

• CI/CD Pipeline (GitHub Actions):

* Push to main branch:

1. Build Frontend: Install dependencies, run tests, build static assets.

2. Build Backend: Install dependencies, run tests, compile TypeScript.

3. Dockerize: Build Docker images for frontend and backend, push to Amazon Elastic Container Registry (ECR).

4. Deploy: Update AWS Elastic Container Service (ECS) Fargate service with new Docker image tags.

5. **Database Migrations

Full Stack Application Blueprint: Comprehensive Deliverable

This document provides a detailed, professional blueprint for a full-stack application, encompassing frontend, backend, database, authentication, deployment, and testing strategies. The goal is to provide a production-ready foundation, complete with clean, well-commented code and actionable configurations.

1. Introduction and Technology Stack Overview

This blueprint outlines a robust, scalable, and maintainable full-stack application using a modern and widely adopted technology stack:

• Frontend: React with TypeScript (Vite for fast development)
• Backend: Node.js with Express.js and TypeScript
• Database: PostgreSQL (Relational Database)
• Authentication: JSON Web Tokens (JWT)
• Containerization: Docker & Docker Compose
• Testing: Jest (Backend), Jest & React Testing Library (Frontend)

This combination offers excellent performance, developer experience, and community support, making it suitable for a wide range of applications.

2. Project Structure

A well-organized project structure is crucial for maintainability. Here's a suggested monorepo-like structure using a root directory:

.
├── README.md
├── docker-compose.yml
├── .env.example
├── backend
│   ├── src
│   │   ├── config
│   │   │   └── index.ts               # Environment variables, database config
│   │   ├── controllers
│   │   │   ├── authController.ts
│   │   │   └── userController.ts
│   │   ├── middleware
│   │   │   └── authMiddleware.ts      # JWT verification
│   │   ├── models
│   │   │   ├── userModel.ts           # Database models/interfaces
│   │   │   └── itemModel.ts
│   │   ├── routes
│   │   │   ├── authRoutes.ts
│   │   │   └── userRoutes.ts
│   │   ├── services
│   │   │   ├── authService.ts         # Business logic
│   │   │   └── userService.ts
│   │   ├── utils
│   │   │   ��── jwt.ts                 # JWT utility functions
│   │   │   └── password.ts            # Password hashing utility
│   │   ├── app.ts                     # Express application setup
│   │   └── server.ts                  # Server entry point
│   ├── tests
│   │   ├── unit
│   │   │   └── authService.test.ts
│   │   └── integration
│   │       └── userRoutes.test.ts
│   ├── package.json
│   ├── tsconfig.json
│   └── Dockerfile
├── frontend
│   ├── src
│   │   ├── api
│   │   │   └── auth.ts                # API client calls
│   │   ├── assets
│   │   ├── components
│   │   │   ├── common
│   │   │   │   └── Button.tsx
│   │   │   └── auth
│   │   │       ├── LoginForm.tsx
│   │   │       └── RegisterForm.tsx
│   │   ├── contexts
│   │   │   └── AuthContext.tsx        # Global auth state
│   │   ├── hooks
│   │   │   └── useAuth.ts
│   │   ├── layouts
│   │   │   └── MainLayout.tsx
│   │   ├── pages
│   │   │   ├── HomePage.tsx
│   │   │   ├── LoginPage.tsx
│   │   │   └── DashboardPage.tsx
│   │   ├── router
│   │   │   └── index.tsx              # React Router setup
│   │   ├── styles
│   │   │   └── index.css
│   │   ├── types
│   │   │   └── index.ts               # Shared TypeScript types
│   │   ├── App.tsx                    # Main App component
│   │   └── main.tsx                   # Entry point
│   ├── public
│   ├── tests
│   │   ├── components
│   │   │   └── Button.test.tsx
│   │   └── pages
│   │       └── LoginPage.test.tsx
│   ├── package.json
│   ├── tsconfig.json
│   ├── vite.config.ts
│   └── Dockerfile

3. Database Design

We'll use PostgreSQL. For demonstration, let's design a simple schema for Users and Items.

3.1. Entity-Relationship Diagram (Conceptual)

• User:

* id (PK, UUID)

* username (UNIQUE)

* email (UNIQUE)

* password_hash

* created_at

* updated_at

• Item:

* id (PK, UUID)

* name

* description

* user_id (FK to User.id)

* created_at

* updated_at

3.2. SQL DDL (Data Definition Language)

-- Enable UUID generation if not already enabled
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

-- Create Users table
CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    username VARCHAR(50) UNIQUE NOT NULL,
    email VARCHAR(255) UNIQUE NOT NULL,
    password_hash VARCHAR(255) NOT NULL,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);

-- Create Items table
CREATE TABLE items (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    name VARCHAR(100) NOT NULL,
    description TEXT,
    user_id UUID NOT NULL,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    CONSTRAINT fk_user
        FOREIGN KEY(user_id)
        REFERENCES users(id)
        ON DELETE CASCADE -- If a user is deleted, their items are also deleted
);

-- Optional: Add indexes for performance
CREATE INDEX idx_users_email ON users(email);
CREATE INDEX idx_items_user_id ON items(user_id);

4. Backend API (Node.js/Express.js with TypeScript)

We'll use pg for PostgreSQL interaction, bcrypt for password hashing, and jsonwebtoken for JWTs.

4.1. Core Server Setup (backend/src/server.ts, backend/src/app.ts)

// backend/src/server.ts
import app from './app';
import { PORT } from './config';
import { connectDB } from './config/db'; // Assuming db connection is in config

const startServer = async () => {
    try {
        await connectDB(); // Connect to the database
        app.listen(PORT, () => {
            console.log(`Server running on http://localhost:${PORT}`);
        });
    } catch (error) {
        console.error('Failed to start server:', error);
        process.exit(1);
    }
};

startServer();

// backend/src/app.ts
import express from 'express';
import cors from 'cors';
import helmet from 'helmet';
import morgan from 'morgan';
import authRoutes from './routes/authRoutes';
import userRoutes from './routes/userRoutes';
import { errorHandler } from './middleware/errorHandler'; // Custom error handling

const app = express();

// Middleware
app.use(cors()); // Enable CORS for all origins (configure for production)
app.use(helmet()); // Secure HTTP headers
app.use(morgan('dev')); // HTTP request logger
app.use(express.json()); // Parse JSON request bodies

// Routes
app.use('/api/auth', authRoutes);
app.use('/api/users', userRoutes);

// Root route (optional)
app.get('/', (req, res) => {
    res.send('API is running...');
});

// Global error handler
app.use(errorHandler);

export default app;

4.2. Database Connection (backend/src/config/db.ts)

// backend/src/config/db.ts
import { Pool } from 'pg';
import { DB_HOST, DB_NAME, DB_PASSWORD, DB_PORT, DB_USER } from './index';

const pool = new Pool({
    user: DB_USER,
    host: DB_HOST,
    database: DB_NAME,
    password: DB_PASSWORD,
    port: parseInt(DB_PORT || '5432'), // Ensure port is number
});

export const connectDB = async () => {
    try {
        await pool.connect();
        console.log('PostgreSQL connected successfully!');
    } catch (err) {
        console.error('PostgreSQL connection error:', err);
        process.exit(1); // Exit process with failure
    }
};

export const query = (text: string, params?: any[]) => pool.query(text, params);

4.3. Authentication Setup (JWT)

Middleware (backend/src/middleware/authMiddleware.ts)

// backend/src/middleware/authMiddleware.ts
import { Request, Response, NextFunction } from 'express';
import jwt from 'jsonwebtoken';
import { JWT_SECRET } from '../config';

// Extend the Request interface to include the user object
declare global {
    namespace Express {
        interface Request {
            user?: { id: string; email: string };
        }
    }
}

export const protect = (req: Request, res: Response, next: NextFunction) => {
    let token;

    if (req.headers.authorization && req.headers.authorization.startsWith('Bearer')) {
        try {
            // Get token from header
            token = req.headers.authorization.split(' ')[1];

            // Verify token
            const decoded = jwt.verify(token, JWT_SECRET!) as { id: string; email: string };

            // Attach user info to request
            req.user = { id: decoded.id, email: decoded.email };

            next();
        } catch (error) {
            console.error('Token verification failed:', error);
            return res.status(401).json({ message: 'Not authorized, token failed' });
        }
    }

    if (!token) {
        return res.status(401).json({ message: 'Not authorized, no token' });
    }
};

Auth Controller (backend/src/controllers/authController.ts)

// backend/src/controllers/authController.ts
import { Request, Response } from 'express';
import * as authService from '../services/authService';
import { generateToken } from '../utils/jwt';

export const registerUser = async (req: Request, res: Response) => {
    const { username, email, password } = req.body;

    if (!username || !email || !password) {
        return res.status(400).json({ message: 'Please enter all fields' });
    }

    try {
        const newUser = await authService.registerUser(username, email, password);
        const token = generateToken(newUser.id, newUser.email);

        res.status(201).json({
            id: newUser.id,
            username: newUser.username,
            email: newUser.email,
            token,
        });
    } catch (error: any) {
        if (error.message.includes('duplicate key')) {
            return res.status(400).json({ message: 'User with this email or username already exists.' });
        }
        res.status(500).json({ message: 'Server error during registration.', error: error.message });
    }
};

export const loginUser = async (req: Request, res: Response) => {
    const { email, password } = req.body;

    try {
        const user = await authService.loginUser(email, password);
        if (!user) {
            return res.status(401).json({ message: 'Invalid credentials' });
        }

        const token = generateToken(user.id, user.email);

        res.status(200).json({
            id: user.id,
            username: user.username,
            email: user.email,
            token,
        });
    } catch (error: any) {
        res.status(500).json({ message: 'Server error during login.', error: error.message });
    }
};

export const getCurrentUser = async (req: Request, res: Response) => {
    // User information is available from the `protect` middleware
    if (req.user) {
        res.status(200).json({
            id: req.user.id,
            email: req.user.email,
            // In a real app, you'd fetch more user details from the DB based on req.user.id
        });
    } else {
        res.status(401).json({ message: 'Not authorized, no user found' });
    }
};

Auth Routes (backend/src/routes/authRoutes.ts)

// backend/src/routes/authRoutes.ts
import { Router } from 'express';
import { registerUser, loginUser, getCurrentUser } from '../controllers/authController';
import { protect } from '../middleware/authMiddleware';

const router = Router();

router.post('/register', registerUser);
router.post('/login', loginUser);
router.get('/me', protect, getCurrentUser); // Protected route

export default router;

4.4. Example API Endpoint (Users)

User Model (backend/src/models/userModel.ts)

// backend/src/models/userModel.ts
export interface User {
    id: string;
    username: string;
    email: string;
    password_hash: string;
    created_at: Date;
    updated_at: Date;
}

User Service (backend/src/services/userService.ts)

// backend/src/services/userService.ts
import { query } from '../config/db';
import { User } from '../models/userModel';

export const getUserById = async (id

This document outlines a comprehensive Full Stack Application Blueprint, ready to guide the development of a robust, scalable, and maintainable application. It details the frontend and backend architectures, database design, authentication strategies, deployment configurations, and testing suites, providing a solid foundation for your development team.

Full Stack Application Blueprint: PantheraConnect

Project Title: PantheraConnect - Collaborative Project Management Platform

Overview:

PantheraConnect is designed to be an intuitive and powerful collaborative platform, enabling teams to efficiently manage projects, tasks, and communications. It provides a seamless user experience for creating projects, assigning tasks, tracking progress, and fostering team collaboration through a modern, responsive interface and a robust, secure backend.

1. Key Technologies Stack

This blueprint leverages a modern, industry-standard technology stack chosen for its performance, scalability, developer experience, and community support.

• Frontend:

* Framework: React.js (with TypeScript)

* State Management: Zustand (lightweight and powerful)

* Styling: Tailwind CSS (utility-first CSS framework)

* Routing: React Router DOM

* Build Tool: Vite

• Backend:

* Framework: Node.js with NestJS (TypeScript, opinionated, highly scalable)

* ORM: Prisma (Next-gen ORM for Node.js & TypeScript)

* Validation: Class-validator & Zod

* Database Driver: PostgreSQL client (via Prisma)

• Database:

* Relational Database: PostgreSQL

• Authentication & Authorization:

* Strategy: JSON Web Tokens (JWT) with Refresh Tokens

* Password Hashing: Bcrypt

• Deployment & Infrastructure:

* Containerization: Docker

* Cloud Provider: AWS (Amazon Web Services)

* CI/CD: GitHub Actions

• Testing:

* Unit/Integration: Jest (Frontend & Backend)

* E2E (End-to-End): Playwright

2. Core Features

The PantheraConnect platform will support the following primary functionalities:

• User Management: Registration, Login, Profile Management, Password Reset.
• Project Management: Create, View, Edit, Delete Projects; Project Archiving.
• Task Management: Create, View, Edit, Delete Tasks; Assign Tasks to Users; Set Due Dates; Task Status Tracking (To Do, In Progress, Done).
• Team Collaboration: Add/Remove Project Members; Role-Based Access Control within Projects.
• Dashboard: Personalized overview of assigned tasks and project status.
• Notifications: In-app notifications for task assignments, status changes, and project updates.
• Search & Filtering: Ability to search and filter projects and tasks.

3. Frontend Architecture & Components

The frontend will be built as a Single Page Application (SPA) using React.js with a modular, component-based architecture to ensure maintainability and scalability.

3.1. Architecture Principles

• Component-Based: Following an Atomic Design methodology (Atoms, Molecules, Organisms, Templates, Pages).
• State Management: Global state managed by Zustand for simplicity and performance. Local component state managed by React hooks.
• Routing: Client-side routing handled by React Router DOM, with protected routes for authenticated users.
• Styling: Utility-first approach with Tailwind CSS, ensuring consistent design and rapid development.
• Data Fetching: React Query (TanStack Query) for efficient data fetching, caching, and synchronization.
• Error Handling: Centralized error boundary components and toast notifications for user feedback.

3.2. Key Frontend Components

• Layout Components:

* AppLayout: Main layout with navigation (Sidebar, Header).

* AuthLayout: Layout for login/registration pages.

• Authentication & User Components:

* LoginForm, RegisterForm, ForgotPasswordForm

* UserProfile, UserAvatar

• Project Management Components:

* ProjectList, ProjectCard

* ProjectDetail (overview, members, tasks)

* ProjectForm (create/edit)

• Task Management Components:

* TaskList, TaskCard

* TaskDetail (description, assignee, due date, status)

* TaskForm (create/edit)

* StatusDropdown, AssigneeDropdown

• Dashboard Components:

* DashboardOverview (summary of projects/tasks)

* MyTasksWidget, RecentProjectsWidget

• Reusable UI Components (Atoms/Molecules):

* Button, Input, Select, Textarea

* Modal, Dialog, Dropdown

* Spinner, LoadingOverlay

* ToastNotification

* EmptyState

3.3. Folder Structure (Example)

src/
├── api/                  # API client logic (React Query hooks)
├── assets/               # Images, icons, fonts
├── components/
│   ├── atoms/            # Basic HTML elements (Button, Input)
│   ├── molecules/        # Groups of atoms (LoginForm, TaskCard)
│   ├── organisms/        # Complex UI sections (ProjectList, TaskDetail)
│   └── layouts/          # Page layouts (AppLayout, AuthLayout)
├── hooks/                # Custom React hooks
├── pages/                # Route-level components (HomePage, ProjectPage)
├── store/                # Zustand stores
├── styles/               # Tailwind config, base styles
├── utils/                # Utility functions (date formatting, validators)
├── App.tsx               # Main application component
├── main.tsx              # Entry point
├── router.tsx            # React Router configuration
└── types/                # TypeScript type definitions

4. Backend API Architecture & Endpoints

The backend will be a robust and scalable RESTful API built with NestJS, following a modular and layered architecture.

4.1. Architecture Principles

• Modular Design: Features organized into NestJS modules (e.g., AuthModule, UsersModule, ProjectsModule, TasksModule).
• Layered Architecture:

* Controllers: Handle incoming HTTP requests, validate input, delegate to services.

* Services: Contain business logic, orchestrate data operations.

* Repositories (via Prisma): Interact directly with the database.

* DTOs (Data Transfer Objects): Define request/response shapes and enforce validation.

• RESTful Principles: Use standard HTTP methods (GET, POST, PUT, DELETE) and status codes.
• Error Handling: Centralized exception filters for consistent error responses.
• Logging: Integrated logging using NestJS's built-in logger, configured for different environments.
• Security: Helmet middleware for common web vulnerabilities, rate limiting for API protection.

4.2. Key Backend Endpoints

4.2.1. Authentication Module (/api/auth)

• POST /api/auth/register: Register a new user.
• POST /api/auth/login: Authenticate user and return JWTs (access and refresh tokens).
• POST /api/auth/refresh: Obtain a new access token using a refresh token.
• POST /api/auth/logout: Invalidate refresh token (optional, for explicit logout).
• POST /api/auth/forgot-password: Initiate password reset.
• POST /api/auth/reset-password: Complete password reset.

4.2.2. User Module (/api/users) - Protected

• GET /api/users/me: Get current authenticated user's profile.
• PUT /api/users/me: Update current authenticated user's profile.
• GET /api/users/:id: Get user by ID (Admin/Project Owner only).
• GET /api/users: List all users (Admin only).

4.2.3. Project Module (/api/projects) - Protected

• POST /api/projects: Create a new project.
• GET /api/projects: List all projects accessible by the user (owner or member).
• GET /api/projects/:id: Get a specific project by ID.
• PUT /api/projects/:id: Update a specific project by ID (Project Owner only).
• DELETE /api/projects/:id: Delete a specific project by ID (Project Owner only).
• POST /api/projects/:id/members: Add a member to a project (Project Owner only).
• DELETE /api/projects/:id/members/:userId: Remove a member from a project (Project Owner only).

4.2.4. Task Module (/api/tasks) - Protected

• POST /api/projects/:projectId/tasks: Create a new task within a project.
• GET /api/projects/:projectId/tasks: List all tasks for a specific project.
• GET /api/tasks/:id: Get a specific task by ID.
• PUT /api/tasks/:id: Update a specific task by ID (Assignee or Project Owner).
• DELETE /api/tasks/:id: Delete a specific task by ID (Project Owner).

4.3. Folder Structure (Example)

src