The basic dispute is this: Iran wants to keep at least some of its nuclear program, which it's had for years and insists is just for peaceful purposes. The outside world believes, with good reason, that Iran's program is at least partly designed to illegally develop a nuclear bomb, and wants the program to stop.
This has been bad for everybody. Iran's economy is crippled by sanctions. The world was facing a possible Iranian nuclear bomb, which would be very dangerous and worsen the already violent Middle East. It looked increasingly like this would end with the US having to choose between letting Iran develop a nuclear bomb or going to war.
This week's nuclear agreement is meant to resolve that years-long fight, to keep Iran from getting a nuclear bomb but let it keep a very small nuclear program, and to do it peacefully.
This process started almost immediately after Iranians elected a moderate president, Hassan Rouhani, in mid-2013. Iran came together in formal negotiations with a group of world powers known as the P5+1: Germany plus the five permanent members of the UN Security Council, which are the US, UK, Russia, China, and France. In April, they announced a "framework" deal of the broad strokes. It looked very favorable to the US and got rave reviews from arms control experts. This week they released a final agreement that filled in the details.
The deal does this: Iran will give up the bulk of its nuclear program, namely its enriched uranium (nuclear fuel) and its centrifuges (which turn fuel into weapons material). That will leave it with a program way too small to build a bomb.
Iran will also submit to extremely invasive inspections. That's to make sure it isn't cheating, for example by sneaking nuclear material off to some secret facility and developing a bomb there. The idea is that Iran knows it can't get away with cheating, and will be punished if it does, so it won't try.
In exchange, the world will remove a lot of the economic sanctions it's placed on Iran, and Iran gets to keep just enough of a nuclear program that it can save face.
The provisions generally last at least 10 years, with some of them lasting 25 years, so this could be around for a long time.
If the deal works, it will prevent Iran from getting a nuclear bomb, it will ease Iran's economic suffering, and it will make war less likely — huge improvements. Arms control experts tend to say this is about the best we could get.
If the deal fails, then we will back where we are now, except that it will be much harder to reimpose those tough economic sanctions. That's a possibility, and deal critics have reason to worry. But this is almost certainly the world's best chance for averting both war and a nuclear Iran, and will likely be remembered as a huge legacy achievement for President Obama.