Lessons from Building Uraan

Building a software product from an idea is very different from building a feature inside an existing application. When you're working on a product, there is no predefined roadmap telling you exactly what to build, which architecture to choose, or what problems users will encounter. You have to make those decisions yourself. What should we build? Who is it for? How should it work? What should the architecture look like? What happens when something fails? How do we know users actually need it? Uraan started from a simple idea: what if people could use AI to create personalized career roadmaps based on their goals, experience, available time, and learning preferences? Turning that idea into an actual product exposed many lessons about product strategy, AI engineering, backend architecture, user experience, and the reality of building software. This is the story of those lessons.

The original concept sounds relatively simple:
User provides their career information → AI generates a personalized roadmap.

At first glance, the architecture seems straightforward:

User
  ↓
Form
  ↓
AI Model
  ↓
Roadmap

But building a useful product quickly makes the problem much larger. The system needs to understand:

• the user's current skill level
• career goals
• learning preferences
• available time
• target duration
• current progress
• roadmap structure
• individual learning tasks
• learning resources
• completed tasks

The architecture therefore starts evolving:
                ┌──────────────┐
                 │    User      │
                 └──────┬───────┘
                        ↓
                ┌───────────────┐
                │   Next.js     │
                │   Frontend    │
                └───────┬───────┘
                        ↓
                ┌───────────────┐
                │   FastAPI     │
                │    Backend    │
                └───────┬───────┘
                        ↓
             ┌────────────────────┐
             │   PostgreSQL       │
             │     Database       │
             └────────────────────┘
                        │
                        ↓
                 ┌────────────┐
                 │  AI Model  │
                 └────────────┘

The lesson was immediate: A product idea is only the beginning. The real work is translating that idea into a system that people can actually use.

It's tempting to start a new project by choosing technologies. For example:

Let's use Next.js, FastAPI, PostgreSQL, and an LLM.

Those are implementation decisions. The first question should instead be: What problem are we solving? For Uraan, the problem was not:

People need an AI application.

The problem was closer to:

People often don't know what they should learn next or how to structure their learning toward a specific career goal.

That distinction matters. Once the problem is clear, technology becomes a tool for solving it.

Problem
  ↓
Users
  ↓
Requirements
  ↓
Product
  ↓
Architecture
  ↓
Technology

Not:

Technology
  ↓
Build Something
  ↓
Find a Problem

The second approach can produce technically impressive software that nobody actually needs.

One of the biggest challenges when building a product is deciding what not to build. It's easy to imagine features:

• AI mentor
• career recommendations
• roadmaps
• progress tracking
• scheduling
• notifications
• analytics
• communities
• job recommendations
• personalized resources
• skill assessments

All of these might be useful eventually. But trying to build everything immediately creates a huge product with little validation. For Uraan, the core experience could be simplified to:

Create Profile
      ↓
Define Career Goal
      ↓
Generate Roadmap
      ↓
View Roadmap
      ↓
Complete Learning Tasks

That is much more manageable. The purpose of an MVP isn't to build a small version of the final product. It's to build the smallest version that allows you to learn whether the core idea is valuable.

One of the biggest differences between traditional applications and AI-powered applications is that AI output can be unpredictable. A traditional function might return:

{
"name": "John",
"age": 25
}

An LLM might instead produce: John is 25 years old and is interested in software engineering... That isn't necessarily useful to an application. If an AI-generated roadmap needs to be displayed, stored, and updated, the application needs predictable structure. For example:

Roadmap
 ├── Title
 ├── Description
 ├── Duration
 ├── Goals
 └── Learning Units
      ├── Day
      ├── Title
      ├── Description
      ├── Type
      ├── Duration
      └── Resource

This means AI engineering isn't simply:
Prompt → Response

It becomes:

User Data
   ↓
Prompt Construction
   ↓
AI Model
   ↓
Structured Output
   ↓
Validation
   ↓
Database
   ↓
Application

The AI is one component of the system. The application still needs to control the data.

Early prototypes often store everything inside a single object. That can work temporarily. But as the product evolves, data relationships become important. For example, Uraan has concepts such as:

User
  │
  └── Profile
       │
       └── Roadmap
            │
            ├── Goals
            │
            └── Learning Units
                  │
                  └── Completion Status

A relational database makes these relationships explicit. Instead of storing one enormous JSON document, different entities can have their own responsibilities. For example:

• users
• profiles
• roadmaps
• learning_units
• progress

This becomes especially important when users need to update individual parts of the application. Suppose a user completes one task. You don't want to regenerate the entire roadmap. You want to update something like: learning_unit.completed = true Good data modeling makes those operations straightforward.

Architecture shouldn't exist independently from product requirements. Consider a requirement like:

Users should be able to continue their roadmap from any device.

That immediately implies things such as:

• persistent data
• authentication
• server-side storage
• API endpoints
• progress tracking

Or:

Users should be able to generate different roadmaps over time.

Now the database needs to support multiple roadmap records. Or:

Learning tasks should support different content types.

The data model needs to represent those types. This creates an important relationship:

Product Requirements
        ↓
Domain Model
        ↓
Data Model
        ↓
API Design
        ↓
Frontend

Architecture is not something you design once at the beginning and never revisit. It evolves with the product.

Uraan uses a separate frontend and backend. The frontend handles the user experience. The backend handles business logic, data, authentication, and AI interactions. The API connects them. For example:

Next.js
   ↓

POST /roadmaps/generate
   ↓
FastAPI
   ↓
Generate Roadmap
   ↓
Save to Database
   ↓
Return Roadmap

Later, the frontend can request:

GET /roadmaps/{id}

and retrieve the stored roadmap. This separation creates a clean boundary:

Frontend
   │
   │ HTTP / JSON
   ↓
Backend API
   │
   ├── Database
   ├── AI Services
   └── Business Logic

It also makes future changes easier. The frontend can change without rewriting the entire backend. The backend can evolve without tightly coupling itself to UI components.

AI applications frequently involve slow operations. Generating a roadmap can involve:

• database operations
• external API calls
• AI inference
• validation
• multiple database writes

This creates an important backend engineering question: Which operations should be asynchronous? For example:

async def generate_roadmap():
    ...

Using async can help when the application spends time waiting for I/O. But simply adding async everywhere doesn't automatically make an application faster. You still need to understand:

• I/O-bound operations
• CPU-bound operations
• database queries
• external API calls
• connection pools
• concurrency
• background jobs

The lesson was broader than Uraan: Use asynchronous programming because the workload benefits from it, not because it sounds more scalable.

One of the biggest differences between traditional CRUD functionality and AI functionality is reliability. A database query usually behaves predictably. An external AI request can fail for many reasons:

• network problems
• API errors
• rate limits
• invalid responses
• malformed structured output
• timeouts
• unexpected content

Therefore, the application needs defensive programming. A simplified workflow might look like:

Generate Request
      ↓
Validate Input
      ↓
Call AI
      ↓
Validate Response
      ↓
Save Data
      ↓
Return Result

If the AI response is invalid:

AI Response
     ↓
Validation Failed
     ↓
Retry / Recover
     ↓
Error Handling

The important lesson is: Never assume an external AI service will always return exactly what you expect.

Adding authentication can initially seem simple:

• Email
• Password

   ↓
Login

But real applications need to answer more questions. What happens when: the user requests their roadmap? another user tries to access it? the session expires? the user logs out? an API request doesn't contain valid credentials? Authentication establishes who the user is. Authorization establishes: What is this user allowed to access? For example:

GET /roadmaps/123

shouldn't simply return roadmap 123. The backend should verify that the authenticated user actually owns or has permission to access that roadmap. This becomes especially important as an application grows.

A simple application might only need:

• Loading
• Success
• Error

But a real product has many states. For example: Roadmap Generation

idle
 ↓
generating
 ↓
success
 ↓
active
 ↓
completed

There can also be failures:

generating
    ↓
failed
    ↓
retry

If these states aren't explicitly designed, the UI can become unpredictable. Buttons may remain disabled. Loading indicators may disappear too early. Users may accidentally submit requests twice. The lesson is: State is part of the product design, not merely frontend implementation detail.

The happy path is usually easy.

User
 ↓
Enter Valid Data
 ↓
Generate Roadmap
 ↓
Success

Real users don't behave like that. What if: the user closes the browser during generation? the AI request times out? the roadmap is generated twice? the user has no career goal? the database request fails? the session expires? the user refreshes the page? the generated content is incomplete? the user changes their profile later? These aren't unusual situations. They are normal software conditions. A production-ready application needs to consider them.

Getting an application running locally is only one stage. A real product needs to move through an environment like:

Local Development
       ↓
Git Repository
       ↓
CI / Testing
       ↓
Production Build
       ↓
Deployment
       ↓
Monitoring

For Uraan, this means thinking about:

• frontend deployment
• backend deployment
• database configuration
• environment variables
• secrets
• CORS
• API URLs
• authentication configuration
• migrations
• logs
• error handling

A feature isn't truly finished when it works on localhost. It's finished when it works reliably in the environment where users will actually use it.

Local development gives you a controlled environment. Production doesn't. You start encountering:

• unexpected requests
• slow networks
• invalid user input
• deployment failures
• database connection issues
• API rate limits
• authentication problems
• browser differences
• performance issues

This is why software engineering extends beyond writing code. The real lifecycle is:

Idea
 ↓
Requirements
 ↓
Design
 ↓
Development
 ↓
Testing
 ↓
Deployment
 ↓
Monitoring
 ↓
Feedback
 ↓
Iteration

Deployment isn't the end. It's another beginning.

When designing a new system, it's tempting to immediately introduce:

• microservices
• Kubernetes
• distributed queues
• multiple databases
• complex caching
• event-driven architecture

These technologies have legitimate uses. But complexity also has a cost. For an early-stage product, a modular monolith may be more appropriate:

Frontend
   ↓
Backend
   ↓
PostgreSQL
   ↓
External Services

As the product grows, individual components can be extracted when there is a real reason.

For example:
                   ┌── API
                    │
Frontend → Backend ─┼── AI Service
                    │
                    ├── Background Jobs
                    │
                    └── Database

Architecture should evolve based on actual constraints. Not hypothetical ones.

When working on a single feature, the primary question might be:

Does this code work?

When building a product, the questions become broader: Can users understand it? Can they recover from errors? Can we maintain it? Can we change it later? Can we monitor it? Can we scale it? Can another developer understand it? Can we deploy it safely? Does the feature actually solve the user's problem? The definition of "good code" becomes much larger. A product isn't just code. It's a system.

Perhaps the biggest lesson is that building an AI product isn't fundamentally different from building other software. AI adds new engineering challenges, but the fundamentals remain. You still need:

• product strategy
• good UX
• reliable APIs
• data modeling
• authentication
• error handling
• testing
• deployment
• monitoring
• security

AI simply introduces another layer:

• Traditional Application
• +
• AI Capabilities

        ↓
AI-Powered Product

The strongest products don't treat AI as magic. They treat AI as another engineering component that needs to be designed, tested, monitored, and improved.

Looking back, the journey can be summarized as:

IDEA
 ↓
"What problem are we solving?"
 ↓
DEFINE USERS
 ↓
"What do they actually need?"
 ↓
MVP
 ↓
"What is the smallest useful version?"
 ↓
ARCHITECTURE
 ↓
"How should the system work?"
 ↓
IMPLEMENTATION
 ↓
"Can we build it reliably?"
 ↓
DEPLOYMENT
 ↓
"Can real users use it?"
 ↓
FEEDBACK
 ↓
"What should we improve?"
 ↓
ITERATION

This cycle never really ends. That's the reality of software products.

Building Uraan reinforced an important belief: The hardest part of software development isn't always writing the code. It's deciding what to build, understanding the problem, designing the system, handling unexpected situations, and continuously improving the product after it reaches real users. AI makes it possible to build products that were difficult or impossible to create previously. But AI doesn't eliminate the need for good engineering. If anything, it makes good engineering more important. An AI-powered product still needs a solid foundation. It needs thoughtful product decisions, reliable infrastructure, secure data handling, good user experience, and an architecture that can evolve. Uraan is an ongoing experiment in that process — taking an idea, turning it into software, learning from the challenges, and improving it one iteration at a time. And that is ultimately what building software is about. Experiment. Build. Evolve.