App Ideas User Guide

app-ideas is a curated collection of 91 application project ideas for developers who want to learn by building. Maintained by Florin Pop and Jim Medlock, the repository organises every idea into three difficulty tiers, gives you a clear objective, an enforceable list of user stories, optional bonus features, and links to the resources you'll need. There is no code to install — the repository is pure documentation that you read, choose from, and build against on your own.

This guide shows you how to navigate the collection, pick projects appropriate to your skill level, build a portfolio from them, and contribute new ideas back to the community.

1. Quick Start

The fastest way to use app-ideas is to skim the README's tiered tables and click straight into an idea's spec file. No checkout, no build step, no dependencies — every project description is a self-contained Markdown document.

1. Open the project on GitHub: github.com/florinpop17/app-ideas.
2. Scroll the README until you find the Tier-1: Beginner Projects, Tier-2: Intermediate Projects, and Tier-3: Advanced Projects tables.
3. Click any project name — for example, Bin2Dec — to jump to its spec page (Projects/1-Beginner/Bin2Dec-App.md).
4. Read the Tier, objective paragraph, User Stories checklist, Bonus features, and Useful links and resources sections.
5. Build the project in any language, framework, or stack you like. The collection is technology-agnostic.

Tip

Every idea spec follows the same shape, defined by Example Guide.md at the repository root: Application Name, Tier, objective paragraph, User Stories (required), Bonus features (optional stretch goals), Useful links and resources, and Example projects. Once you've read one spec you can read any of the other 90 in well under a minute.

What you get from a single spec page

Smallest possible "Hello World"

The Projects/1-Beginner/Hello-App.md idea is the gentlest on-ramp:

Display a personalised greeting in the user's native language using only HTML,
CSS, and a small amount of JavaScript. Three required user stories, one bonus.

Pick it. Spend an afternoon. Ship it. Add it to your portfolio. Pick the next one.

Note

The repository contains documentation only — there is no compiled binary, no npm install, and no runtime. Every project you build from these specs is yours; the spec is just the brief.

2. Installation

You don't install app-ideas. There is nothing to compile, no package to download, no service to run. The repository is consumed in one of three ways, in order of friction:

Method 1: Browse on GitHub (recommended)

GitHub renders every Markdown file with anchored navigation, syntax highlighting, and clickable links. Bookmark the README and use it as your starting page.

https://github.com/florinpop17/app-ideas

Tip

The README's three tier tables are the canonical index. Treat them as the table of contents for the entire collection.

Method 2: Clone locally

Useful if you want offline access, plan to grep the specs, or are preparing a contribution.

HTTPS

git clone https://github.com/florinpop17/app-ideas.git
cd app-ideas

SSH

git clone git@github.com:florinpop17/app-ideas.git
cd app-ideas

GitHub CLI

gh repo clone florinpop17/app-ideas
cd app-ideas

After cloning, the directory layout is:

app-ideas/
├── README.md                    # Tier tables + project metadata
├── CONTRIBUTING.md              # How to submit a new idea
├── Example Guide.md             # Template for new idea PRs
├── CODE_OF_CONDUCT.md           # Contributor Covenant v1.4
├── LICENSE                      # MIT
├── app-ideas.png                # Repository banner
├── coderabbit.jpg               # Sponsor banner
└── Projects/
    ├── 1-Beginner/              # 37 spec files
    ├── 2-Intermediate/          # 33 spec files
    └── 3-Advanced/              # 21 spec files

Important

The default branch is master (not main). When you fork and submit pull requests, target master.

Method 3: Fork for contributions

If you intend to submit a new project idea, fork the repository on GitHub before cloning so your branch is pushable:

gh repo fork florinpop17/app-ideas --clone
cd app-ideas
git checkout -b add-my-new-idea

System requirements

Note

Building any project from these specs will require additional tools (a code editor, language runtimes, framework SDKs, API keys for some specs). Those are per-project and listed in each idea's "Useful links and resources" section, never centrally.

3. Configuration

app-ideas has no runtime, no settings file, and no environment variables. There is nothing to configure on the consumer side.

The only "configuration" decisions you make are personal:

Note

If you intend to contribute a new idea, you will need to configure your fork: set your Git identity, enable signed commits if your account requires them, and ensure your master branch tracks florinpop17/app-ideas. See Section 5 for the full contribution recipe.

4. Core Usage

The whole product is a navigable index of project ideas. Core usage means: pick a tier, pick an idea, build it.

4.1 Difficulty tiers — the three buckets

The collection defines exactly three tiers. Every idea is assigned to exactly one of them.

Tip

The README tables in the repository root list every project with a one-line description. Skim them in tier order — the descriptions are short enough to triage in two minutes per tier.

4.2 The 37 Beginner ideas (Tier 1)

Beginner projects can typically be completed in a single afternoon to a single weekend, using only HTML, CSS, and vanilla JavaScript (or any equivalent stack):

Tip

If you're brand new to JavaScript, start with Hello, Calculator, Pomodoro Clock, and Notes App in that order. They build on each other and cover almost every fundamental DOM and storage skill.

4.3 The 33 Intermediate ideas (Tier 2)

Tier 2 introduces persistence, third-party APIs, more advanced UI patterns, and your first taste of backend coordination:

Note

Several Tier 2 ideas (Currency Converter, GitHub Profiles, Book Finder) require an API key from a third-party service. Each spec lists the API's signup URL in its "Useful links and resources" section. Keys are free for personal use.

4.4 The 21 Advanced ideas (Tier 3)

Tier 3 expects backend competence, persistence, and often integration with external services like Slack, Discord, or NASA's open APIs:

Important

Tier 3 ideas often span multiple repositories or services in a real implementation (frontend + backend + external API). The spec describes the user-visible behaviour; you choose the architecture.

4.5 Anatomy of an idea spec

Every spec adheres to the template defined in Example Guide.md:

# Application Name

**Tier:** 1-Beginner | 2-Intermediate | 3-Advanced

A descriptive paragraph answering:
- What is the purpose of this application?
- What resources are needed to complete the project?

## User Stories

- [ ] User can ... (required)
- [ ] User can ...

## Bonus features

- [ ] User can ... (optional stretch goals)

## Useful links and resources

External docs, Wikipedia entries, API references.

## Example projects

Community implementations to reference *after* you've built your own.

Tip

The unchecked task-list checkboxes (- [ ]) are your personal tracker. Fork the repo, copy the spec into your own project, and tick them off as you implement each story.

4.6 What app-ideas is not

The collection is intentionally minimal. It does not provide:

• Starter code, scaffolding, boilerplates, or templates beyond the idea spec
• Solutions or reference implementations (the Example projects sections link to community work, not official solutions)
• Tests, grading rubrics, or completion certificates
• A web UI for browsing the ideas (a website is mentioned as a future plan in the README, but is not yet shipped)
• An automated way to filter ideas by tech stack, API used, or feature

Note

If you want to filter ideas by stack — for example "all ideas that use the GitHub API" — search the repository on GitHub. Section 5 has a recipe for this.

5. Common Tasks

Recipe 1: Pick a first project as a complete beginner

Goal: Choose a Tier 1 project that matches your current skills and ship it this weekend.

Steps:

1. Open the README's Tier-1: Beginner Projects table.
2. Filter mentally for projects that don't require an API: Bin2Dec, Calculator, Color Cycle, Hello, Pomodoro Clock, Stopwatch App, Vigenere Cipher, Word Frequency, Roman to Decimal Converter.
3. Click into the spec and read the User Stories section. If you understand every bullet, the project is at-or-below your level.
4. If a story uses an unfamiliar term (e.g. "callback", "regex"), open the linked resource in the Useful links and resources section first.
5. Build to satisfy every required user story before attempting any bonus.

Verify: Every required - [ ] user story checkbox can be ticked off when looking at your live app.

Tip

Resist the temptation to start with a tier above your level. Beginner projects are deliberately small — finishing five small projects beats abandoning one big one.

Recipe 2: Build a portfolio with five ideas

Goal: Use app-ideas to assemble a coherent portfolio of five completed projects across the three tiers.

Steps:

1. Pick 2 Beginner, 2 Intermediate, 1 Advanced project. A balanced split shows range.
2. Choose projects that span different concerns: one UI-only, one API-consuming, one with persistence, one with state, one with external integration. Suggested combo: Pomodoro Clock (UI + state), Notes App (persistence), GitHub Profiles (API), Markdown Previewer (parsing), Chat App (real-time).
3. Build each project in its own GitHub repository so each one is independently linkable on a CV.
4. Use a consistent README template across your repos: screenshot, demo URL, tech stack, "credit: idea from florinpop17/app-ideas".
5. Deploy each one (GitHub Pages, Netlify, Vercel, or Render are all free for static and small dynamic apps).
6. Link your five repos from a single portfolio page.

Verify: Each repo has a green deploy badge, a screenshot, and a working live URL. Your portfolio page links to all five.

Tip

Implement two of the projects in different stacks (e.g. one in vanilla JS, one in React). The contrast lets a reviewer see your range without you having to claim it.

Recipe 3: Find ideas that match a specific tech stack

Goal: Locate every idea that suits the technology you want to practise — for example, "all ideas that work well with the GitHub API".

Steps:

1. Use GitHub's repository search:

https://github.com/florinpop17/app-ideas/search?q=GitHub+API&type=code

2. Or grep locally after cloning:

git clone https://github.com/florinpop17/app-ideas.git
cd app-ideas
grep -ril "github.com/api" Projects/
grep -ril "openweathermap" Projects/
grep -ril "canvas" Projects/

3. Open each matching spec and confirm the API or stack is core to the idea (not just a footnote in Example projects).

Verify: The search returns specs whose User Stories explicitly mention the technology you searched for.

Note

The spec metadata is not machine-structured (no front-matter, no JSON sidecar). Stack-based discovery is search-based, not query-based.

Recipe 4: Contribute a new idea

Goal: Submit a brand-new project idea for inclusion in the collection.

Prerequisites:

• A GitHub account
• A new idea that isn't already present (search the repository first; check open issues — issues #1094, #1102, #1077, #1076, #1078 are pending project-idea proposals as of this writing)

Steps:

1. Fork the repository on GitHub.
2. Clone your fork and create a feature branch:

gh repo fork florinpop17/app-ideas --clone
cd app-ideas
git checkout -b add-color-picker-app

3. Decide the tier. Use the same criteria as Section 4: backend or auth -> Tier 3, third-party API or non-trivial state -> Tier 2, otherwise Tier 1.
4. Copy Example Guide.md into the appropriate tier directory and rename it:

cp "Example Guide.md" Projects/1-Beginner/Color-Picker-App.md

5. Fill in every section of the template: title, Tier: line, descriptive paragraph, User Stories, Bonus features, Useful links and resources, Example projects.
6. Add the new project to the matching tier table in README.md. Match the existing alphabetical/insertion ordering and column alignment.
7. Commit and push:

git add Projects/1-Beginner/Color-Picker-App.md README.md
git commit -m "Add Color Picker App (Tier 1)"
git push origin add-color-picker-app

8. Open a pull request against florinpop17/app-ideas master. Use the new idea label.

Verify: Your PR shows two file changes — the new spec file and the README table update — and renders cleanly in GitHub's diff view.

Important

The CONTRIBUTING guide requires one PR per suggestion. Don't bundle multiple ideas in a single PR.

Recipe 5: Contribute an example implementation to an existing idea

Goal: Add a community implementation link to an idea you've already built.

Steps:

1. Build your implementation and host it (GitHub repository + live demo).
2. Open the spec for the idea you implemented (e.g. Projects/1-Beginner/Bin2Dec-App.md).
3. Append a bullet to the Example projects section linking your repo. Match the existing format:

- [Bin2Dec built with <stack>](https://github.com/yourname/your-repo)
    - [Live preview](https://your-demo-url.example.com)

4. Submit a PR with a clear title, e.g. Add Bin2Dec Vue example.

Verify: Your PR diff shows only the bullet you appended and your live preview URL works.

Tip

Adding an example implementation is the lowest-friction way to make your first contribution to the project — you'll typically get reviewed and merged faster than a brand-new-idea PR.

Recipe 6: Translate the project documentation

Goal: Translate the README or a project spec into another language for non-English-speaking learners.

Steps:

1. Search the repository's open and closed PRs for existing translations to your target language. The project doesn't yet have a formal i18n structure, so translations have historically been ad-hoc.
2. Open an issue first to discuss the approach with maintainers — confirm whether they want a parallel README-<lang>.md or a separate translations/<lang>/ directory.
3. After alignment, translate the chosen file in your fork, preserving every link, every code block, and every table-column alignment.
4. Submit one PR per translated file.

Verify: Side-by-side comparison shows your translation matches the structure of the source. All links still resolve.

Warning

Translation accuracy matters more than completeness. A partial, accurate translation is more useful than a full, machine-translated one. If your source language for translation is the README, double-check tier names, project names, and the contribution rules — those are load-bearing terms learners rely on.

6. Troubleshooting

Because app-ideas is a documentation repository, "errors" usually mean something is unclear, missing, or out of date in a spec. There is no runtime to crash.

Issue: A spec's external link returns 404 or redirects unexpectedly

Cause: Idea specs link to community implementations, tutorials, and live demos hosted on third-party services (CodePen, Heroku, personal domains). Those services may be retired, the author may delete the repo, or a free-tier deploy may be deactivated.

Solution:

1. Treat the spec's User Stories as the source of truth — the link rot in Example projects does not invalidate the brief.
2. If you can fix the link (you find a working mirror, or you've built a replacement), submit a PR updating the entry.
3. If the link is broken with no replacement, you may submit a PR removing it. Reference issue #1092 (proposing removal of a stale Pomodoro Clock link) as precedent.

Prevention: When adding an example link, prefer GitHub repositories over Heroku/codepen URLs — repositories survive longer than free-tier deploys.

Issue: A spec's API or external service has been deprecated or now requires payment

Cause: Several Tier 2 and Tier 3 ideas reference free APIs that have since changed pricing or shut down (a recurrent issue in API-driven specs). The spec text won't always be updated immediately.

Solution:

1. Read the spec's User Stories — they describe the user-facing behaviour, which is independent of any specific API.
2. Substitute any equivalent API. For example, if a weather API is mentioned but now paid, OpenWeatherMap, Open-Meteo, and the National Weather Service all expose free endpoints with similar shapes.
3. Document your substitution in your project's README.

Prevention: Don't hardwire an API into your build. Wrap it in a thin adapter layer so swapping providers is a single-file change.

Issue: I can't tell which tier my idea belongs in

Cause: Tier boundaries in the README are stated in audience terms (Tier 1 "early-stage learners", Tier 2 "comfortable with API services", Tier 3 "implementing backend applications and database services"), not in mechanical criteria.

Solution: Apply this decision tree:

1. Does the idea require a database, persistent server, auth, or a real-time channel? -> Tier 3.
2. Does it require a third-party API or non-trivial state across multiple views? -> Tier 2.
3. Otherwise, it's Tier 1.

Prevention: When reviewing similar ideas already in the collection, place yours in the same tier as the closest existing match.

Issue: My PR adding a new idea was closed without merging

Cause: The most common reasons (per maintainer feedback in the issue tracker):

1. The idea duplicates an existing one (always search first).
2. The PR bundled multiple changes (the CONTRIBUTING guide requires one PR per suggestion).
3. The spec didn't follow Example Guide.md exactly.
4. The README's tier table wasn't updated.

Solution:

1. Re-read CONTRIBUTING.md carefully.
2. Use git diff master and confirm only the two expected files are touched (the new spec, and the README).
3. Open a fresh PR — don't argue in the closed one.

Prevention: Before pushing, verify your spec by viewing it on your fork's branch in the GitHub UI. The rendering will match what reviewers see.

Issue: I'm not sure if my implementation "counts" as complete

Cause: The collection has no automated grader and no canonical reference solution.

Solution: A project is complete when every required - [ ] user story checkbox in the spec can be ticked off by exercising your live app. Bonus features are explicitly optional and should not be attempted until the required stories are done.

Prevention: Copy the spec's user-story list into your project's README and tick checkboxes as you go. This gives you (and reviewers of your portfolio) a clear definition-of-done.

Issue: The README links to a "future website" that doesn't exist yet

Cause: The README mentions plans to "create a website where you can easily browse through all of the projects" as a future direction. As of this writing the website has not shipped.

Solution: Use the GitHub-rendered README as the canonical browsing UI. Bookmark it.

Prevention: None needed — this is a known roadmap item, not a defect.

Note

For real-time issue tracking, the project's open issues at github.com/florinpop17/app-ideas/issues are your canonical reference. Recent activity centres on new-idea proposals (#1094 Post Feed App, #1102 Tier-2 Post Feed App, #1077 Joke / Quote Generator, #1076 Tic Tac Toe, #1078 Color Picker) and example-showcase posts (#1114 ExoVault NASA Exoplanet Archive Explorer, #1113 NutraFlux Calorie Counter implementation).

7. FAQ

Q: Do I have to build the projects in any specific language or framework?

No. The specs are intentionally technology-agnostic. Use whatever stack you want to learn or already know — JavaScript, Python, Go, Rust, Swift, Kotlin, Dart, Elixir, anything. The user stories describe user-facing behaviour, not implementation choices.

Q: Can I skip the user stories and just build "the spirit" of the project?

You can, but the user stories exist so a reviewer (an employer, an interviewer, a peer) can verify your implementation against an objective rubric. If you skip them, you lose the "complete vs. incomplete" framing that makes these projects portfolio-grade.

Q: Is there a recommended order to build the Tier-1 projects in?

The README doesn't prescribe an order, but a reasonable progression is: Hello -> Calculator -> Stopwatch App -> Pomodoro Clock -> Notes App -> Quiz App. This sequence introduces DOM, state, timers, persistence, and structured data in that order.

Q: How do I know if an idea is already taken or oversaturated for portfolio purposes?

Search GitHub for the project name (e.g. "Bin2Dec"). The community has built thousands of implementations of the popular Tier-1 ideas. Saturation isn't bad — your reviewer cares about your implementation, not whether it's novel.

Q: Can I use these ideas commercially?

The repository is MIT-licensed (see LICENSE). The ideas themselves cannot be copyrighted — they're descriptions of common application categories. Your implementation is yours to license however you like.

Q: What's the difference between "User Stories" and "Bonus features"?

User stories are the contract: implementing all of them defines a complete project. Bonus features are stretch goals — extensions you tackle after the base is working, to push your skills further or to differentiate your portfolio entry.

Q: Why are some idea specs much shorter than others?

The Tier-1 specs tend to be short (one paragraph + four user stories) because the projects are small. Tier-3 specs are longer because they often define separate components (e.g. Battleship Game Engine has separate user-story sections for the engine and the presentation layer).

Q: Can I propose a new tier — "Tier 4: Expert" — for very large projects?

The collection has stuck to three tiers since inception. The maintainers haven't signalled openness to a fourth tier. If you have an idea too large for Tier 3, consider splitting it into multiple Tier-3-shaped sub-projects.

Q: Are the example-project links curated for quality?

Loosely. They're community-submitted via PR. Treat them as inspiration, not endorsement. Read your own spec carefully and build from the user stories first — only consult the example projects if you get stuck or want to compare approaches at the end.

Q: How do I contribute a translation of the README?

Open an issue first to align with maintainers on file naming and directory structure. Translations don't yet have a formal home in the repository. See Recipe 6 in Section 5.

Q: I have an idea that crosses multiple tiers (e.g. a "minimal Tier-1 version" and a "fully-featured Tier-3 version"). What do I do?

Submit two separate PRs in two separate spec files (one per tier), with the spec descriptions cross-referencing each other ("for a simpler take see X"). One PR per suggestion is the contribution rule.

Q: How often is the collection updated?

The project receives contributions on an ongoing basis — the recent issue tracker shows multiple project-idea proposals and showcase submissions per month. The repo's master branch is the canonical, always-current state.

Q: Where can I see other developers' implementations of these projects?

Each spec's Example projects section links to community implementations. For broader exploration, search GitHub topics like app-ideas, app-ideas-collection, or the project name directly.

Q: Can I print this entire collection as a PDF and work through it offline?

You can clone the repository (Section 2) and view the Markdown locally with any reader. Printing the full set of 91 specs is possible but unnecessary — most learners reference one spec at a time.