This guide walks you through setting up and running the Star Wars Character Explorer application with a separated frontend and backend architecture.

starwars/
├── client/    # React frontend (Vite)
└── server/    # Express backend

Ensure you have the following installed:

• Node.js (v14.0.0 or higher)
• pnpm
• Git

git clone https://github.com/mdranaa/starwars.git
cd starwars

Install dependencies for both the frontend and backend:

cd client && pnpm install
cd ../server && pnpm install

Create a .env file inside the client/ folder with the following content:

# client/.env
VITE_API_BASE_URL=http://localhost:5000/api

Create a .env file inside the server/ folder with the following content:

# server/.env
PORT=5000
SWAPI_BASE_URL=https://swapi.tech/api

Run the frontend and backend concurrently in development mode.

Terminal 1: Start Backend

cd server
pnpm dev
# or: npm run dev

Terminal 2: Start Frontend

cd client
pnpm dev
# or: npm run dev

• Frontend: http://localhost:5173
• Backend API: http://localhost:5000/api

cd client
pnpm build

This creates a production build in client/dist/.

Ensure your server/index.js (or entry point) serves the API (and optionally the frontend static files if using a full-stack deployment).

You can deploy the contents of client to platforms like:

• Vercel

Deploy the Express server to services like:

• Render

Ensure the hosting provider sets the PORT env variable and runs the server entry file (server/dist/index.js or equivalent).

If deploying with Husky and encountering .git not found errors:

• Remove or disable "prepare": "husky install" from package.json
• Or use: npm install --ignore-scripts

Ensure CORS is properly configured in the backend to allow requests from the frontend origin.

If a port is already in use:

npx kill-port 5000
# or change the PORT in server/.env

• Explore the codebase inside client/ and server/
• Add new features or characters
• Implement caching or more advanced API features

If you run into issues:

1. Check this README again
2. Look for logs in the console
3. Create a GitHub issue in the project repository

Happy exploring the Star Wars universe! ✨

This document explains the rationale behind key design and implementation decisions made during the development of the Star Wars application.

Decision: Implement a React frontend with an Express.js backend proxy to the SWAPI.

Rationale:

• API Abstraction: The backend proxy abstracts the SWAPI, allowing us to transform and enhance the data before sending it to the client.
• Error Handling: Centralized error handling in the backend provides consistent error responses.
• Future Extensibility: This architecture allows for future enhancements like caching, authentication, and additional data sources.
• CORS Mitigation: Eliminates potential CORS issues that might occur with direct browser-to-SWAPI calls.

Decision: Organize the frontend into reusable components with clear separation of concerns.

Rationale:

• Reusability: Components like Card and Pagination can be reused across different parts of the application.
• Maintainability: Smaller, focused components are easier to maintain and test.
• Collaboration: Component-based structure facilitates parallel development by multiple team members.
• Testing: Isolated components are easier to test independently.

Decision: Use React with TypeScript for the frontend.

Rationale:

• Type Safety: TypeScript provides static type-checking, reducing runtime errors and improving code quality.
• Developer Experience: Better IDE support, autocomplete, and documentation.
• Maintainability: Types serve as documentation and help with refactoring.
• Scalability: As the application grows, TypeScript helps manage complexity.

Decision: Use Tailwind CSS for styling instead of CSS-in-JS or traditional CSS.

Rationale:

• Development Speed: Tailwind's utility-first approach allows for rapid UI development.
• Consistency: Predefined design tokens ensure consistency across the application.
• Performance: No runtime CSS-in-JS overhead.
• Customization: The tailwind.config.js file allows for theme customization while maintaining design system constraints.
• Responsive Design: Built-in responsive utilities make it easy to create mobile-first designs.

Decision: Use Express.js for the backend proxy.

Rationale:

• Lightweight: Express is minimalist and doesn't add unnecessary overhead.
• Familiarity: Express is widely used and understood by developers.
• Middleware Ecosystem: Rich ecosystem of middleware for logging, security, etc.
• Performance: Express is performant enough for the proxy requirements.

Decision: Create a dedicated API service layer in the frontend.

Rationale:

• Separation of Concerns: Keeps API interaction logic separate from UI components.
• Reusability: API functions can be reused across different components.
• Maintainability: Centralized place for API-related logic and error handling.
• Testing: Easier to mock API calls for testing components.

Decision: Implement a dark-themed UI inspired by the Star Wars universe.

Rationale:

• Thematic Relevance: Dark theme aligns with the space setting of Star Wars.
• User Experience: Reduces eye strain during extended use.
• Visual Appeal: Creates a modern, immersive experience.
• Content Focus: Dark backgrounds make information stand out.

Decision: Display s in a card-based grid layout.

Rationale:

• Visual Organization: Cards provide clear visual separation between items.
• Responsive Design: Card grids naturally adapt to different screen sizes.
• User Familiarity: Card layouts are common in modern web applications.
• Content Hierarchy: Cards allow for consistent presentation of information.

Decision: Implement traditional pagination instead of infinite scrolling.

Rationale:

• API Compatibility: SWAPI natively supports pagination.
• Performance: Limits the number of items rendered at once.
• User Control: Gives users explicit control over navigation.
• Accessibility: More accessible than infinite scrolling for some users.

Decision: Implement server-side search through the SWAPI endpoint.

Rationale:

• Efficiency: Avoids fetching all s to perform client-side filtering.
• Performance: Reduces client-side processing and memory usage.
• Scalability: Works regardless of the total number of s in the database.
• Accuracy: Leverages the API's native search capabilities.

Decision: Create a dedicated page for details with related information.

Rationale:

• Information Density: Allows for comprehensive display of data without cluttering the main listing.
• Focus: Users can focus on one at a time.
• Related Data: Provides space to show related information like films, species, and homeworld.
• Navigation: Clean URL structure for direct linking and sharing.

Decision: Implement performance optimizations in React components.

Rationale:

• User Experience: Smooth, responsive UI improves user satisfaction.
• Resource Usage: Efficient rendering reduces CPU and memory usage.
• Mobile Experience: Optimized components perform better on lower-powered devices.

Decision: Use Framer Motion for selective, purposeful animations.

Rationale:

• User Feedback: Animations provide visual feedback for user actions.
• Attention Guidance: Subtle animations draw attention to important elements.
• Performance: Framer Motion is optimized for performance with React.
• Accessibility: Animations respect user preferences (reduced motion).

Decision: Plan for implementing caching in future iterations.

Rationale:

• Performance: Caching would reduce API calls and improve response times.
• User Experience: Faster data retrieval creates a more responsive application.
• API Respect: Reduces load on the SWAPI servers.

Decision: Consider adding offline support in future versions.

Rationale:

• User Experience: Allow users to access previously viewed content offline.
• Progressive Enhancement: Improves the application's resilience.
• Modern Web Standards: Aligns with progressive web app best practices.

The design decisions outlined in this document were made to create a performant, maintainable, and user-friendly Star Wars application. These decisions balance immediate user needs with future extensibility, creating a solid foundation for the application to grow.

Each decision was made with consideration for both technical and user experience factors, striving to create an application that is not only functionally complete but also enjoyable to use.

This document outlines the quality assurance and testing strategies for the Star Wars application.

1. Ensure all application features work as expected
2. Verify the application is responsive across different devices
3. Validate proper error handling and edge cases
4. Confirm the application meets performance standards
5. Ensure accessibility compliance

• Development: Local development environment
• Staging: Pre-production environment (future implementation)
• Production: Live environment (future implementation)

Objective: Test individual components and functions in isolation

Tools: Jest, React Testing Library

Areas to Test:

• API service functions
• Utility functions
• React component rendering
• State management logic

Example Test Cases:

• Verify API functions make correct requests
• Test pagination logic functions
• Validate card renders correctly with given props
• Test search input validation

Objective: Test interactions between components and services

Tools: Jest, React Testing Library, Supertest

Areas to Test:

• Component interactions
• API service integration with components
• Routing functionality
• Backend API endpoints

Example Test Cases:

• Verify search results display correctly when search is performed
• Test navigation between different pages
• Validate details page loads and displays data
• Test backend API endpoint responses

Objective: Test complete user flows from start to finish

Tools: Cypress, Playwright

Areas to Test:

• User journeys
• Cross-browser compatibility
• Network request handling

Example Test Cases:

• Complete flow: Search for → View details → Return to search
• Pagination: Navigate through multiple pages of results
• Error handling: Test application behavior when API is unavailable

Objective: Ensure the application performs well under various conditions

Tools: Lighthouse, WebPageTest

Areas to Test:

• Page load times
• API response times
• Resource usage

Example Test Cases:

• Measure time to first contentful paint
• Test application performance with slow network conditions
• Evaluate performance on low-end devices

Objective: Ensure the application is accessible to all users

Tools: axe, Lighthouse

Areas to Test:

• Keyboard navigation
• Screen reader compatibility
• Color contrast
• ARIA attributes

Example Test Cases:

• Verify all interactive elements are keyboard accessible
• Test with screen readers
• Check color contrast ratios
• Validate semantic HTML structure

1. ** Listing**

   • Verify s are displayed in a grid
   • Confirm pagination controls work correctly
   • Test loading states display properly

2. Search Functionality

   • Test searching for existing s
   • Test searching with special s
   • Verify no results message for non-existent s
   • Test clearing search results

1. Data Display

   • Verify all information displays correctly
   • Test loading states
   • Confirm related data (films, homeworld, species) displays properly

2. Navigation

   • Test back button functionality
   • Verify direct URL access works

1. Device Testing
   • Test on mobile devices (various sizes)
   • Test on tablets
   • Test on desktop (various sizes)
   • Verify layout adapts appropriately

1. API Errors

   • Test application behavior when API returns errors
   • Verify error messages are user-friendly
   • Test retry functionality (if implemented)

2. Not Found Scenarios

   • Test 404 page for non-existent routes
   • Verify behavior when accessing details for non-existent

Bug ID: [AUTO-GENERATED]
Title: [BRIEF DESCRIPTION]
Environment: [DEV/STAGING/PROD]
Browser/Device: [BROWSER VERSION/DEVICE MODEL]
Severity: [CRITICAL/HIGH/MEDIUM/LOW]
Steps to Reproduce:
1.
2.
3.

Expected Result:
Actual Result:
Screenshots/Videos:
Additional Information:

• Critical: Application crash, data loss, security vulnerability
• High: Major feature not working, blocking user flow
• Medium: Feature working incorrectly but workaround exists
• Low: Minor issues, cosmetic problems

// Example component test
import { render, screen } from '@testing-library/react';
import Card from '../components/Card';

test('renders  card with correct name', () => {
  render(<Card id="1" name="Luke Skywalker" />);
  const nameElement = screen.getByText(/Luke Skywalker/i);
  expect(nameElement).toBeInTheDocument();
});

// Example API endpoint test
import request from 'supertest';
import app from '../server';

describe(' API', () => {
  test('GET /api/s returns paginated results', async () => {
    const response = await request(app).get('/api/s');
    expect(response.status).toBe(200);
    expect(response.body).toHaveProperty('results');
    expect(response.body).toHaveProperty('totalPages');
    expect(response.body).toHaveProperty('currentPage');
  });
});

1. Continuous Integration:

   • Run unit and integration tests on every pull request
   • Run end-to-end tests nightly or before releases

2. Manual Testing:

   • Perform exploratory testing after major feature additions
   • Execute test scenarios before releases
   • Test on actual devices periodically

3. Regression Testing:

   • Run full test suite before releases
   • Focus on areas affected by recent changes

Generate test reports after each test run, including:

• Test coverage metrics
• Pass/fail statistics
• Performance metrics
• Accessibility compliance report

1. Implement visual regression testing
2. Add load testing for the backend
3. Set up continuous performance monitoring
4. Implement user testing sessions

This QA/Test Plan provides a comprehensive approach to ensuring the quality of the Star Wars application. The plan should be reviewed and updated as the application evolves.

The Star Wars is a web application that allows users to explore s from the Star Wars universe. The application fetches data from the Star Wars API (SWAPI) through a custom Express.js backend proxy, and presents it in a user-friendly interface built with React.

The application follows a client-server architecture:

1. Frontend: React application built with TypeScript and Tailwind CSS
2. Backend: Express.js server acting as a proxy to the SWAPI
3. External API: SWAPI (https://swapi.tech/api)

┌────────────────┐     ┌─────────────────┐     ┌──────────────┐
│                │     │                 │     │              │
│  React Client  │────▶│  Express Server │────▶│  SWAPI API   │
│                │◀────│                 │◀────│              │
└────────────────┘     └─────────────────┘     └──────────────┘

• React: UI library
• TypeScript: Type safety
• React Router: Client-side routing
• Tailwind CSS: Styling
• Framer Motion: Animations
• Axios: HTTP client
• Lucide React: Icon library

The frontend follows a component-based architecture with the following structure:

src/
├── components/           # Reusable UI components
│   ├── Card.tsx
│   ├── Grid.tsx
│   ├── Footer.tsx
│   ├── Layout.tsx
│   ├── LoadingSpinner.tsx
│   ├── Navbar.tsx
│   ├── Pagination.tsx
│   └── SearchResults.tsx
├── pages/                # Page components
│   ├── DetailsPage.tsx
│   ├── HomePage.tsx
│   └── NotFoundPage.tsx
├── services/             # API service functions
│   └── api.ts
├── App.tsx               # Main application component
├── index.css             # Global styles
└── main.tsx              # Application entry point

1. ** Listing**: Displays a grid of Star Wars s with pagination
2. ** Search**: Allows users to search for s by name
3. ** Details**: Shows detailed information about a selected
4. Responsive Design: Works on mobile, tablet, and desktop devices

• Express.js: Web server framework
• Axios: HTTP client for API requests
• CORS: Cross-Origin Resource Sharing middleware

The backend exposes the following API endpoints:

The backend performs the following transformations on the SWAPI data:

1. Standardizes Response Format: Ensures consistent data structure across endpoints
2. Fetches Related Data: For details, fetches related films, homeworlds, and species
3. Error Handling: Provides meaningful error responses

1. User interacts with the React UI
2. React components make API calls to the Express backend
3. Express backend proxies requests to SWAPI
4. SWAPI returns data to the Express backend
5. Express backend processes and transforms the data
6. React components receive and render the data

1. Pagination: Implemented to limit data load and improve performance
2. Loading States: Provide feedback during API calls
3. Error Handling: Graceful handling of API errors
4. Caching: Future enhancement to reduce API calls

1. Client-Side Caching: Implement React Query or similar for efficient data caching
2. Server-Side Caching: Add Redis or similar to cache SWAPI responses
3. Offline Support: Implement service workers for offline functionality
4. Authentication: Add user accounts for favorites and personalization
5. Advanced Search: Filter by multiple criteria (species, films, etc.)

1. Backend Proxy: Used to handle data transformation and avoid CORS issues
2. Component Structure: Modular components for reusability and maintainability
3. Tailwind CSS: Chosen for rapid development and consistent styling
4. API Service Layer: Centralized API calls for better organization

1. Unit Testing: Test individual components and functions
2. Integration Testing: Test component interactions
3. End-to-End Testing: Test complete user flows
4. Accessibility Testing: Ensure the application is accessible to all users

This documentation provides an overview of the technical implementation of the Star Wars application. For more detailed information, refer to the code comments and specific component documentation.