apps — codebuddy-real-campaign

Module: apps-codebuddy-real-campaign Cohesion: 0.80 Members: 0

apps — codebuddy-real-campaign

The apps/codebuddy-real-campaign directory serves as a collection of distinct, self-contained Node.js application projects, each representing a "level" or challenge solution within a coding campaign. These projects demonstrate various full-stack development patterns, from simple CLI tools to authenticated web applications and AI integrations.

This document provides an overview and detailed breakdown of each project within this campaign, focusing on their purpose, architecture, key components, and how they function.

Campaign Overview

The apps/codebuddy-real-campaign module contains the following levels:

Note that for Levels 2 and 3, v2 versions of the projects are provided. The campaign-report.json indicates that the initial (non-v2) submissions for these levels had validation issues, and the v2 directories contain the corrected or improved implementations. This documentation will focus on the v2 implementations where available.

1. Level 1: CLI Task Tracker

This project implements a basic command-line interface (CLI) for managing a list of tasks.

Purpose

To provide a simple, dependency-free Node.js CLI application that allows users to add, list, mark as complete, and remove tasks, with local JSON persistence.

Architecture & Key Components

The application is a single-file Node.js script (index.js) that parses command-line arguments and performs operations on a local tasks.json file.

Core Functionality

The index.js script exposes the following functions:

The CLI commands are handled via a switch statement on process.argv[2]: add, list, complete, remove.

CLI Command Flow

graph TD
    A[Start: node index.js <command> <args>] --> B{Parse process.argv[2]};
    B -- "add" --> C[addTask(args.join(' '))];
    B -- "list" --> D[listTasks()];
    B -- "complete" --> E[completeTask(parseInt(args[0]))];
    B -- "remove" --> F[removeTask(parseInt(args[0]))];
    C --> G[saveTasks()];
    E --> G;
    F --> G;
    G --> H[End];
    D --> H;

Data Persistence

Tasks are stored in a tasks.json file in the same directory as index.js. The fs module is used for reading (fs.readFileSync) and writing (fs.writeFileSync) this file.

Testing

Usage

To run the CLI, navigate to apps/codebuddy-real-campaign/level-1-cli/task-tracker and use node index.js [arguments].

Examples:

2. Level 2: Notes Board Web Application (v2)

This project implements a full-stack web application for managing notes, featuring an Express.js backend and a vanilla JavaScript frontend.

Purpose

To build a web application that allows users to create, read, update, and delete notes, with local JSON file persistence.

Architecture & Key Components

The application follows a classic client-server architecture.

Backend API (server.mjs)

The Express server uses lowdb for simple JSON file-based persistence. It defines the following API endpoints:

The nanoid library is used to generate unique IDs for new notes.

Frontend (public/app.js)

The app.js script handles all client-side interactions:

Data Persistence

Notes are stored in db.json using lowdb. The db.read() and db.write() methods manage the file operations.

Client-Server Interaction

graph TD
    A[Browser: app.js] --> B{HTTP Requests};
    B -- GET /api/notes --> C[Express Server: server.mjs];
    B -- POST /api/notes --> C;
    B -- PUT /api/notes/:id --> C;
    B -- DELETE /api/notes/:id --> C;
    C --> D[lowdb: db.json];
    D --> C;
    C --> B;
    B --> A;

Testing

Usage

  1. Navigate to apps/codebuddy-real-campaign/level-2-webapp-v2.
  2. Install dependencies: npm install.
  3. Start the server: npm start (or npm run dev for development with nodemon).
  4. Open your browser to http://localhost:3001.

3. Level 3: AI Support Desk (v2)

This project implements an AI-powered chat application that leverages the Google Gemini API for conversational responses.

Purpose

To build a full-stack web application that provides a multi-turn conversational AI support desk, demonstrating integration with an external AI service.

Architecture & Key Components

The application consists of an Express.js backend handling AI interactions and a vanilla JavaScript frontend for the chat interface.

Backend API (server.mjs)

The Express server handles API requests and integrates with the Google Gemini API:

The GoogleGenerativeAI client is initialized with the API key from environment variables (GOOGLE_API_KEY or GEMINI_API_KEY).

Frontend (public/app.js)

The app.js script manages the chat interface:

Client-Server-AI API Flow

graph TD
    A[Browser: app.js] --> B{POST /api/chat (message, history)};
    B --> C[Express Server: server.mjs];
    C --> D{GoogleGenerativeAI: model.startChat()};
    D --> E[Gemini API];
    E --> D;
    D --> C;
    C --> B{JSON Response (response)};
    B --> A;

AI Integration

The backend uses the @google/generative-ai library to interact with the Gemini API. The model.startChat() method is crucial for maintaining conversational context by passing the history array.

Error Handling & Validation

Testing

Usage

  1. Navigate to apps/codebuddy-real-campaign/level-3-ai-chat-v2.
  2. Install dependencies: npm install.
  3. Set your Google Gemini API key as an environment variable (GOOGLE_API_KEY or GEMINI_API_KEY).
  4. Start the server: npm start.
  5. Open your browser to http://localhost:3337 (or the port specified in server.mjs).

4. Level 4: Authenticated Task Manager (SQLite)

This project implements a full-stack task manager application with user authentication, session management, and task CRUD operations, using SQLite for data persistence.

Purpose

To build a secure task management application where users can register, log in, and manage their personal tasks, with all operations protected by authentication.

Architecture & Key Components

This application features an Express.js backend with authentication middleware and a vanilla JavaScript frontend.

Backend API (server.mjs)

The Express server uses better-sqlite3 for database interactions, bcrypt for password hashing, and express-session with connect-session-sqlite for session management.

Authentication Endpoints:

Task Management Endpoints (protected by isAuthenticated middleware):

Key Backend Logic:

Frontend (public/app.js)

The app.js script handles client-side authentication and task management:

Authentication Flow (Simplified)

graph TD
    A[Browser: app.js] --> B{POST /api/register or /api/login};
    B --> C[Express Server: server.mjs];
    C -- Hash Password (bcrypt) --> D[SQLite: users table];
    D --> C;
    C -- Create Session (express-session) --> E[SQLite: sessions table];
    E --> C;
    C --> B{Success/Error Response};
    B --> A;
    A -- Subsequent Task Requests --> F{GET/POST/PUT/DELETE /api/tasks};
    F --> G[Express Server: isAuthenticated middleware];
    G -- Check req.session.userId --> E;
    E --> G;
    G -- If authenticated --> D;
    D --> G;
    G --> F{Task Data Response};
    F --> A;

Data Persistence

User accounts, tasks, and session data are all stored in a single SQLite database file, database.db. The better-sqlite3 library provides synchronous and efficient access to the database.

Testing

  1. Registers a new user.
  2. Logs in the user.
  3. Adds multiple tasks.
  4. Lists tasks to verify addition.
  5. Updates a task.
  6. Deletes a task.
  7. Logs out the user.
  8. Attempts task operations while logged out (expected to fail).

It cleans up the database files (database.db.json and database.db.json.tmp) before and after execution.

Usage

  1. Navigate to apps/codebuddy-real-campaign/level-4-auth-sqlite.
  2. Install dependencies: npm install.
  3. Start the server: npm start.
  4. Open your browser to http://localhost:3000.

Campaign Report Summary (campaign-report.json)

The campaign-report.json file provides a snapshot of the validation results for each level at a specific point in time. It indicates whether the automated validation for each level passed (validationOk: true) or failed (validationOk: false), along with the detailed output of the validation command.

As observed in the provided report:

This report highlights the iterative nature of development and testing, where initial attempts might fail and require subsequent corrections (as seen with the v2 versions).

Contribution & Maintenance

Each "level" within apps/codebuddy-real-campaign is designed to be a standalone project. When contributing or maintaining: