Building toplivres, Part Two – Learning Goals, User Stories, and Design Decisions

TL;DR

• Tools: Flask + SQLite with SQLAlchemy, Marshmallow, JWT, Pytest.

• Goals: Learn auth, schema validation, and ORM basics.

• User stories: Partners place orders & report sales; admins confirm and track everything.

• Design choices: Merge orders & sales into one model; compute stock via positive/negative quantities.

• MVP: Auth, core business rule (no new order without sales report), validation, unit tests, Postman-tested API.

1. Introduction

After writing about how I arrived at toplivres in Part One, I realized I needed to formalize my approach. The project wasn’t just about building something; it was about structured learning and solving a real problem. In this post, I walk through how I defined my learning goals, the core user stories, and my initial design decisions.

Toplivres is a learning project bridging backend foundations to full-stack app development. Phase 1 focuses on building an MVP API that implements core business rules.

2. Tools & Environment

Before even defining user stories, I had already started setting up my environment. In hindsight, this says a lot about how I learn: I like to touch the tools early, even if I don’t yet know the full plan.

• Backend framework: I chose Flask. Not because it’s the trendiest (FastAPI was tempting), but because I wanted to learn by building things more “from scratch.” Flask gives you just enough scaffolding, but still leaves space to understand what’s happening under the hood.

• Database: I started with SQLite for local development. It was simple, lightweight, and kept me moving. I set it up in a way that I could later switch to PostgreSQL for production.

• Extensions & packages: I brought in flask-sqlalchemy, flask-migrate, marshmallow, and marshmallow-sqlalchemy. For authentication, flask-jwt-extended. For testing, pytest.

One thing I learned here is that setup choices aren’t just technical — they reflect your learning goals. For example, choosing Flask over FastAPI meant I’d have to write more boilerplate, but that was part of the learning.

3. Learning Goals

Before jumping into code, I forced myself to pause and think: What do I actually want to learn with toplivres?

I picked three goals:

• Authentication and authorization — I wanted to stop treating login systems like a black box. How do tokens actually work? What happens when I log out?

• Schema-based validation — I kept writing messy routes where half the logic was just “is this input correct?” I wanted to clean that up with proper serialization/validation.

• ORM practice — I knew Python syntax, but I avoided SQL. Learning an ORM was my chance to define tables, relationships, and write queries without panicking.

Looking back, defining these goals was a turning point. At this stage, I wasn’t chasing shiny new topics anymore. But pair programming with AI came with its own trap: whenever a new problem popped up, GPT always had something else to try. Sometimes that was useful, sometimes it just derailed me.

One example: we spent hours trying to build a fancy “Flask seed command” to populate my database with fake data. It sounded cool, but the fake data didn’t even follow my business rules, and in the end a simple python seed.py would have done the job. That’s when I realized: the goal isn’t always to make things clever — it’s to make them work.

4. User Stories

At first, I didn’t know I was writing what developers call workflows or user stories. I was just trying to picture how different people would interact with the system, step by step. Looking back, I realize this was already a way of modeling the system.

Here’s what I came up with:

For partners (bookstore owners / customers):

Note: In my codebase, this role was originally called customer. Here I use partner because it better reflects the business relationship.

• Log in to my account

• Browse available books

• View my current inventory

• Place an order

• Cancel an order (unless it’s already confirmed for delivery)

• Submit a sales report

• Rule: I cannot place a new order until I’ve submitted a report for my last one

• View history of my orders

For admins:

• Create new partner accounts

• Block or suspend partner accounts

• View orders + sales history for all partners

• Delete orders or sales reports if needed

• Receive a notification when a new order is placed

• View total inventory across all partners

Writing these down forced me to think beyond “just CRUD.” It made me ask:

• Who is using the system?

• What are their roles?

• What rules connect one action to another?

For example, that rule “No new order until the last order has feedback” came from the real depot-vente workflow I was trying to digitize. At the time, I just thought of it as a practical rule. Later I realized it’s what developers call a business rule.

Some of these user stories came from my own notes, others were nudged by GPT when I pair-programmed with it. That was useful because it helped me rank them: which ones are core and must be built now, and which ones can wait until later phases.

5. Data Models

Initially, GPT suggested four models: Book, Location, Delivery, and SalesReport. But once I started writing user stories and thinking about rules, I realized it made more sense to simplify:

• Replace Location with User, and differentiate roles with a role field (partner vs admin).

• Merge Delivery and SalesReport into one model I called Operation, with a companion OperationItem.

This was my first real design trade-off. By storing positive quantities for orders and negative quantities for sales, I could compute stock levels dynamically with a single SQL query. That trick simplified reporting and gave me a clear sense of how small design decisions can save work later.

6. Minimal Viable Product (MVP)

To avoid tutorial hell and feature creep (the trap of endlessly adding features), I defined a strict MVP. The goal was not “complete CRUD everywhere,” but getting the essential business rules working in a usable API.

✅ MVP Features

1. Authentication & Roles

   • JWT auth with admin and partner roles.

   • Admins manage accounts, partners place orders and report sales.

2. Core Business Logic

   • Create/List Books.

   • Create/List Orders (positive quantities).

   • Create/List Sales Reports (negative quantities).

   • Business rule: “No new order without a sales report for the previous one.”

   • Instead of hard delete, an order can be marked as cancelled to preserve history.

3. Validation & Tests

   • Marshmallow schemas for clean request/response validation.

   • Unit tests for critical endpoints.

🎯 MVP Milestone

All endpoints tested with Thunder Client (VS Code extension). I have plans for documentation and examples using Flasgger + Swagger UI.

7. HTTP Coverage & Reflection

Reflection
Designing this table taught me that API design is more than CRUD — it’s about enforcing business rules, handling permissions, preserving history, and keeping scope manageable. It also gives me the feeling that someone else could test the API and understand it without me explaining every detail.

8. Next Steps

Looking ahead, I want to keep toplivres practical and extend it in directions that make it more realistic:

• Prototype a frontend

• Harden the backend for production (security, error handling, deployment)

• Explore reporting queries and analytics (e.g., sales by partner, most requested books, inventory health)

These steps will let toplivres move from being a “rules API” to something closer to a small product that shows value to both partners and admins.

Conclusion

Writing this post forced me to look back at decisions I made quickly at the time — sometimes with GPT nudging me, sometimes out of frustration. In hindsight, those choices shaped how I understand backend work: not just building endpoints, but thinking in terms of rules, roles, and trade-offs.

Toplivres is still a work in progress, but it already taught me that:

• The tools are less important than the clarity of goals and rules.

• Pair programming with AI is powerful, but it’s also easy to derail without focus.

Next, I want to experiment with a small frontend, polish the backend for production, and maybe share code snippets or diagrams to make the logic clearer.

If you’re also learning backend or using AI as a coding partner, I’d love to hear your stories or tricks.

Personal note: This project is teaching me as much about patience as it is about code.