Architecting Your Project with Claude

In this lab, you will complete the “Plan your application structure” step of this project the way professional teams do: by producing a written, reviewed, and approved architecture document before any code is written. You will use Claude in the AI as Architect role to draft the plan, while you act as the Product Manager who interrogates it, requests revisions, and gives final sign-off. Planning before coding is one of the highest-leverage habits in software development, and learning to direct an AI architect (rather than passively accepting its first draft) is a core skill in AI-native development. Plan for approximately 45 minutes.

Scenario

You have just joined a small product team as its Product Manager. The team is about to build one of three front-end applications (the project option you selected for this module), and company policy is firm: no implementation work begins until the Product Manager approves a written architecture document.

Your team’s architect is Claude. Architects propose; Product Managers challenge, verify against requirements, and approve. If the architecture misses an edge case, ships without error handling, or drifts beyond the requirements, that is your responsibility to catch now, when a fix costs one sentence, rather than later, when it costs a rewrite.

The one rule of this lab: Claude produces architecture only. Outlines, element trees, function signatures, pseudocode, and data-flow descriptions are all allowed. Implementation code (working HTML files, CSS rules, JavaScript function bodies) is not. You will enforce this rule with the role prompt in Part 2, and you will not write any implementation code yourself during this lab either.

Part 1: Confirm Your Project Kickoff (about 5 minutes)

Complete this lab after you select your project option and before you begin coding.

1. Confirm you have chosen one of the three project options from this module:

   • Option 1: IP Address Tracker (IP Geolocation API by IPify, with LeafletJS for maps)
   • Option 2: URL Shortening API Landing Page (bitly API)
   • Option 3: REST Countries API with Color Theme Switcher (REST Countries API)

2. Download and unzip the starter files for your chosen option (the download links are on the option pages in this module). Inside, you will find a README.md, a style-guide.md, design images, and starter assets. You will need the brief, user stories, README.md, and style-guide.md in Part 2.

3. Initialize a Git repository in your project folder and create your first commit:

   cd path/to/your-project-folder
   git init
   git add .
   git commit -m "Initial commit: starter files"

4. Create a new public repository on GitHub (this is the same repository you will submit for the module project), then connect and push:

   git remote add origin https://github.com/<your-username>/<your-repository-name>.git
   git branch -M main
   git push -u origin main

Your commit history now has a clear starting point. Instructors will use this history to verify that your architecture document was committed before your implementation work.

Part 2: Set Up Claude in the Architect Role (about 5 minutes)

You may complete this lab in either the Claude web app or Claude Code. Both paths use the same role prompt. Copy it exactly:

You are acting as a senior software architect for a front-end web project.
Your role in this conversation is ARCHITECT ONLY. Follow these rules for
the entire conversation:

1. Produce architecture artifacts only: outlines, element trees, function
   signatures, pseudocode, and data-flow descriptions.
2. Do not write implementation code. No working HTML documents, no CSS
   rules, no JavaScript function bodies. If I ask for implementation code,
   remind me that this conversation is for architecture only.
3. Ask clarifying questions when requirements are ambiguous instead of
   guessing.
4. When I request a revision, revise only the sections I name and end your
   response with a short summary of what changed.

I am the Product Manager. I will review your plan, request revisions, and
give final approval. Do not treat any plan as final until I reply with the
single word "Approved."

Path A: claude.ai (recommended if you prefer a chat interface)

1. Sign in at https://claude.ai  with your Per Scholas-provided Claude Pro account.
2. Create a new Project and paste the role prompt above into the Project’s custom instructions. Using a Project’s custom instructions is the reliable way to enforce the role, because the instructions apply to every conversation inside the Project.
3. Start a new conversation inside the Project. In your first message, paste the brief and user stories from your chosen option page, followed by the full contents of the starter README.md and style-guide.md. You may paste them across more than one message if they are long; tell Claude to wait until you say the materials are complete.

Path B: Claude Code (recommended if you want Claude to read the starter files directly)

1. Install Claude Code if you have not already, then start it inside your project folder:

   npm install -g @anthropic-ai/claude-code
   cd path/to/your-project-folder
   claude

2. If you are prompted to log in, run /login and use your Per Scholas-provided Claude account.

3. Press Shift+Tab to cycle permission modes until Plan Mode is active. In Plan Mode, Claude Code proposes plans without editing any files, which is exactly the constraint the Architect role requires.

4. Paste the role prompt above as your first message, then ask Claude to read the README.md and style-guide.md in the folder. Paste the brief and user stories from your option page as well: the starter README.md contains the original Frontend Mentor version of the challenge, and the option page in this module is the authoritative version for this course.

Part 3: Request the Architecture Draft (about 10 minutes)

Once Claude has the role prompt and all project materials, request the draft. Use this prompt template, replacing the bracketed API text with the line for your option:

Draft an architecture document for this project with exactly five sections:

1. Semantic HTML Structure: an element tree (an indented outline, not
   code) showing the landmark elements (header, main, footer, and nav
   where appropriate), every major component of the interface, and
   accessibility notes such as heading order, label associations, and
   alt text requirements.

2. CSS Layout Strategy: a mobile-first plan describing the layout
   technique (Flexbox, Grid, or both) for each major section, the
   breakpoints you recommend so the layout matches both the provided
   mobile design and the provided desktop design, and how the colors and
   fonts from style-guide.md will be organized (for example, as CSS
   custom properties).

3. JavaScript Logic Breakdown: a list of every function or module you
   recommend, each with a one-line single responsibility, its inputs,
   and its outputs. Signatures and pseudocode only.

4. API Integration Plan: the full request flow for
   [Option 1: the IP Geolocation API by IPify, plus LeafletJS map setup]
   [Option 2: the bitly API]
   [Option 3: the REST Countries API]
   including when requests fire, what the user sees while a request is
   loading, how failed requests and invalid input are caught and shown
   to the user, and any API keys or rate limits the plan must account
   for.

5. Data-Flow Walkthrough: a plain-text, numbered trace of one complete
   user interaction in this app, from the user action to the rendered
   result, naming which function from section 3 handles each step.

Remember: architecture only, no implementation code.

Steps:

1. Send the prompt and read the entire draft carefully. Do not skim.
2. If Claude asks clarifying questions, answer them using the option brief and designs.
3. If Claude includes implementation code anywhere, invoke the role rule: tell it to replace the code with signatures or pseudocode and regenerate that section. Enforcing the boundary is part of the lab.
4. Keep the draft on screen for Part 4. Do not approve anything yet. First drafts are a starting point, not a deliverable.

Part 4: Review the Draft as Product Manager (about 15 minutes)

Now do the real work of this lab. Audit the draft against your option’s requirements and this module’s evaluation criteria, using this checklist:

• User story coverage: every user story on your option page maps to at least one element, function, or flow in the plan. Trace each one.
• Responsive design: the CSS strategy defines breakpoints that account for both the mobile and desktop designs, mobile-first.
• Accessibility: the plan addresses semantic HTML, form labels, alt text, and keyboard-reachable interactive elements, since accessibility is a graded criterion for the project.
• Error handling: the plan covers a failed API request, empty input, and invalid input (for example, a malformed IP address or URL, or a country search with no matches).
• Loading states: the plan says what the user sees between the request firing and the response rendering.
• Scope creep: nothing in the plan goes beyond the user stories and project requirements. Extra features cost time you do not have; cut them.

Then:

1. Identify at least three substantive problems, gaps, or questionable decisions. If the draft looks flawless, look harder: probe the edge cases and ask Claude to justify its choices. Example revision requests:

   • “Your plan does not cover what happens when the API request fails. Revise the JavaScript Logic Breakdown and the API Integration Plan to include an error state and name the function responsible for rendering it.”
   • “The CSS Layout Strategy lists only one breakpoint. The designs include distinct mobile and desktop layouts. Justify that single breakpoint or add what is missing.”
   • “Section 1 does not say where form validation error messages appear in the document structure or how they are announced to screen readers. Add both.”
   • “Section 3 gives one function two responsibilities: fetching data and rendering it. Split it and update the Data-Flow Walkthrough to match.”

2. Send each revision request as its own message, one at a time, and read the revised section Claude returns.

3. For each request, record three things in your notes (you will need them for the Review Log in Part 5): your request, a one-or-two sentence summary of Claude’s revision, and your decision (accept or reject) with a one-sentence rationale. Rejecting a weak revision and pushing back again is a valid and encouraged outcome; record the follow-up in the same log entry.

4. When all five sections pass your checklist, reply to Claude with the single word Approved.

Part 5: Assemble, Sign Off, and Commit ARCHITECTURE.md (about 10 minutes)

1. Create a file named ARCHITECTURE.md at the root of your project repository, using this structure:

   # Architecture: <Your Project Option Name>
    
   This architecture was drafted by Claude in the Architect role and
   reviewed and approved by the Product Manager before implementation
   began.
    
   ## 1. Semantic HTML Structure
    
   ## 2. CSS Layout Strategy
    
   ## 3. JavaScript Logic Breakdown
    
   ## 4. API Integration Plan
    
   ## 5. Data-Flow Walkthrough
    
   ## Product Manager Review Log
    
   ### Revision Request 1
    
   - **Request:**
   - **Claude's revision (summary):**
   - **Decision and rationale:**
    
   ### Revision Request 2
    
   - **Request:**
   - **Claude's revision (summary):**
   - **Decision and rationale:**
    
   ### Revision Request 3
    
   - **Request:**
   - **Claude's revision (summary):**
   - **Decision and rationale:**
    
   ## Sign-Off
    
   Architecture approved by <your name>, Product Manager, on <date>,
   before implementation began.

2. Fill in the five sections with the final approved versions from your conversation, and fill in the Review Log from your Part 4 notes. Add more log entries if you made more than three revision requests.

3. Claude Code users: you may exit Plan Mode (press Shift+Tab to cycle modes) and ask Claude Code to write ARCHITECTURE.md from the approved plan, since writing the planning document is not implementation code. Read the permission request before approving it, and read the finished file before committing: you are signing off on it.

4. Commit and push:

   git add ARCHITECTURE.md
   git commit -m "Add approved architecture document before implementation"
   git push

5. Optional but encouraged: use the Share button on your Claude conversation to create a public link, and paste that link at the top of your Product Manager Review Log. If sharing is disabled in your workspace, copy a short transcript excerpt of one revision exchange into the log instead.

Submission Guidelines

Submit the link to your project’s public GitHub repository using the Start Assignment link on Canvas. This is the same repository you will continue to use for the module project.

This lab is graded complete/incomplete. To earn a complete, your repository must contain ARCHITECTURE.md at its root, and the file must include:

1. All five architecture sections: Semantic HTML Structure, CSS Layout Strategy (mobile-first, with breakpoints), JavaScript Logic Breakdown (responsibilities, inputs, and outputs), API Integration Plan (including error handling), and Data-Flow Walkthrough.
2. A Product Manager Review Log documenting at least three substantive revision requests, each with a summary of Claude’s revision and your accept or reject decision with a one-sentence rationale.
3. A dated sign-off statement confirming the architecture was approved before implementation began.

Instructors will check your repository’s commit history to confirm that ARCHITECTURE.md was committed before the bulk of your implementation commits, so complete this lab before you begin coding, not after.