BidRadar Development Progress

█████████░░░░░░░░░░░ 9/60

Current phase: Implementation Foundations

Current milestone: Create the BidRadar development environment

Previous article: Part 8 — Writing the BidRadar Master Build Prompt

Next article: Part 10 — Creating the FastAPI Backend Foundation

Primary deliverables:

bidradar/
README.md
docker-compose.yml
.env.example
.gitignore

Application code generated: Project foundation only

Introduction

After eight planning articles, we are finally ready to start building BidRadar.

However, before Google AI Studio generates our first backend service or React component, we need a solid development environment.

Many AI-generated projects fail because developers immediately ask the AI to create application code without first creating a proper project structure.

The result is usually:

• inconsistent folders
• duplicated dependencies
• configuration files scattered across the repository
• broken imports
• poor Docker support
• missing environment variables
• difficult deployments

Professional software teams solve this by creating the development foundation first.

That is exactly what we will do in this article.

Our objective is not to build features.

Our objective is to create a development environment that remains stable for the entire BidRadar project.

Objectives

After completing this article we will have:

• A Git repository
• A monorepo structure
• Backend project
• Frontend project
• Documentation folder
• Infrastructure folder
• Docker configuration
• Python virtual environment
• Node environment
• Shared environment variables
• Git ignore rules
• Development scripts
• Initial README
• Health check applications
• Local development workflow

Why a Monorepo?

There are two common approaches.

Multiple repositories

backend/
frontend/
infrastructure/
documentation/

Advantages:

• Smaller repositories
• Independent versioning

Disadvantages:

• Harder dependency management
• More difficult onboarding
• Multiple CI pipelines
• Cross-repository coordination

Monorepo

bidradar/

containing:

backend/
frontend/
docs/
docker/
scripts/
tests/

Advantages

• One Git repository
• One issue tracker
• Shared documentation
• Easier onboarding
• Single CI pipeline
• Consistent versioning

For BidRadar, a monorepo is the better choice.

Recommended Folder Structure

Our initial repository should look like this.

bidradar/
│
├── backend/
│   ├── app/
│   ├── tests/
│   ├── alembic/
│   ├── requirements/
│   ├── pyproject.toml
│   └── README.md
│
├── frontend/
│   ├── src/
│   ├── public/
│   ├── package.json
│   ├── vite.config.ts
│   └── README.md
│
├── docs/
│   ├── project-vision.md
│   ├── product-requirements.md
│   ├── architecture.md
│   ├── database-schema.md
│   ├── api-specification.md
│   ├── design-system.md
│   └── master-build-prompt.md
│
├── docker/
│
├── infrastructure/
│
├── scripts/
│
├── tests/
│
├── .env.example
├── .gitignore
├── docker-compose.yml
└── README.md

Notice that every major concern has its own dedicated location.

Why Separate Backend and Frontend?

Although FastAPI and React work closely together, they are different applications.

Keeping them separated allows:

• independent builds
• independent testing
• Docker isolation
• cleaner dependency management
• future scalability

The backend never imports frontend code.

The frontend never imports backend code.

Communication occurs exclusively through the REST API.

Creating the Repository

Create the project directory.

mkdir bidradar
cd bidradar

Initialize Git.

git init

Create the initial folders.

mkdir backend
mkdir frontend
mkdir docs
mkdir docker
mkdir infrastructure
mkdir scripts
mkdir tests

The repository is now ready.

Creating the Python Environment

Inside the backend folder:

cd backend

Create a virtual environment.

Windows:

python -m venv .venv

Linux/macOS:

python3 -m venv .venv

Activate it.

Windows

.venv\Scripts\activate

Linux/macOS

source .venv/bin/activate

Always activate the environment before installing packages.

Installing Backend Dependencies

Initially install only the essentials.

pip install fastapi
pip install uvicorn
pip install sqlalchemy
pip install alembic
pip install psycopg
pip install python-dotenv

Later articles will introduce:

• Celery
• Redis
• pgvector
• Pydantic Settings
• OpenAI SDK / Gemini SDK
• Authentication libraries
• Object storage clients

Keep the initial installation minimal.

Creating requirements Files

Instead of one large requirements file, create a requirements folder.

backend/
requirements/

Suggested files:

base.txt
development.txt
production.txt

Example:

development.txt

contains:

-r base.txt
pytest
black
ruff
mypy

This makes dependency management much cleaner.

Creating pyproject.toml

Rather than scattering tool configuration across many files, use:

pyproject.toml

Configure:

• Ruff
• Black
• Pytest
• Mypy

inside a single file where possible.

Installing Node.js

Verify installation.

node -v
npm -v

Use a current LTS version.

If Node is missing, install it before continuing.

Creating the React Application

Inside:

frontend

Create the application.

npm create vite@latest

Choose:

React
TypeScript

Install dependencies.

npm install

Run the development server.

npm run dev

If successful you should see the default Vite page.

Why Vite?

Vite provides:

• extremely fast startup
• fast hot reload
• TypeScript support
• modern tooling
• excellent React integration

It is currently one of the best choices for enterprise React projects.

Creating .gitignore

Create one repository-level file.

Example entries:

.venv/
node_modules/
__pycache__/
.env
dist/
build/
.pytest_cache/
.vscode/settings.json
coverage/
*.log

Do not commit:

• secrets
• generated builds
• virtual environments
• caches

Environment Variables

Create:

.env.example

Example:

APP_NAME=BidRadar
APP_ENV=development
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_NAME=bidradar
DATABASE_USER=postgres
DATABASE_PASSWORD=password
REDIS_URL=redis://localhost:6379
API_PREFIX=/api/v1

Never commit the real .env file.

Only commit .env.example.

README.md

Every repository should start with documentation.

Example sections:

Project Overview
Technology Stack
Getting Started
Development
Docker
Environment Variables
Folder Structure
Contributing
License

Future developers should be able to clone the project and begin working without guessing.

Installing Docker Desktop

Docker allows every developer to work with identical services.

Verify installation.

docker --version

and

docker compose version

If these commands work, Docker is ready.

docker-compose.yml

Initially we only need infrastructure.

Example services:

• PostgreSQL
• Redis

Future articles will add:

• Backend
• Frontend
• Workers
• Object storage

Starting simple reduces complexity.

PostgreSQL Service

The initial PostgreSQL container should expose:

• port 5432
• persistent volume
• database name
• username
• password

Use environment variables rather than hardcoded credentials.

Redis Service

Redis will later support:

• background jobs
• caching
• distributed locks

For now it simply needs to run locally.

Starting Infrastructure

Start Docker.

docker compose up -d

Verify.

docker ps

You should see PostgreSQL and Redis running.

VS Code Workspace

Open the repository.

code .

Recommended extensions:

• Python
• Ruff
• Docker
• GitHub Pull Requests
• SQLTools
• PostgreSQL
• Tailwind CSS IntelliSense
• ESLint

These improve developer productivity.

Recommended Workspace Settings

Useful defaults include:

• format on save
• organize imports
• trim trailing whitespace
• newline at end of file

Keeping formatting automatic prevents unnecessary Git changes.

Python Interpreter

Inside VS Code:

Select Interpreter

Choose:

backend/.venv

Using the wrong interpreter is one of the most common causes of missing-import errors.

Backend Health Check

Create a minimal FastAPI application.

from fastapi import FastAPI
app = FastAPI()
@app.get("/health")
def health():
    return {"status": "ok"}

Run:

uvicorn app.main:app --reload

Visit:

http://localhost:8000/health

Expected response:

{
    "status": "ok"
}

At this stage we are only verifying the environment.

Frontend Health Check

Run:

npm run dev

Open:

http://localhost:5173

If the default Vite screen appears, the frontend is working.

Git Workflow

Initial commits should remain small.

Suggested sequence:

Commit 1

Initialize BidRadar repository

Commit 2

Add backend foundation

Commit 3

Add frontend foundation

Commit 4

Configure Docker

Avoid giant commits containing unrelated work.

Branch Strategy

Suggested branches:

main
develop
feature/*

Example:

feature/backend-foundation
feature/authentication
feature/opportunity-module

This scales well as the project grows.

Development Workflow

Our daily workflow should become:

Pull latest code
↓
Activate Python environment
↓
Start Docker
↓
Run backend
↓
Run frontend
↓
Develop feature
↓
Run tests
↓
Commit
↓
Push

Consistency reduces mistakes.

Common Problems

Wrong Python Interpreter

Symptom:

Import "fastapi" could not be resolved.

Solution:

Select the correct virtual environment.

Missing Node

Symptom:

'node' is not recognized

Solution:

Install Node.js and restart the terminal.

npm Missing Script

Symptom:

Missing script: dev

Cause:

Running the command outside the frontend folder.

Solution:

cd frontend
npm run dev

Docker Not Running

Symptom:

Cannot connect to Docker daemon

Solution:

Start Docker Desktop.

PostgreSQL Connection Refused

Possible causes:

• container stopped
• incorrect port
• incorrect password

Verify:

docker ps

Repository Standards

Every folder should contain only files related to its responsibility.

Avoid placing:

• SQL scripts
• documentation
• images
• deployment files

inside unrelated folders.

Organization becomes increasingly important as the project grows.

Google AI Studio Prompt

Once the repository has been created, use Google AI Studio with the following prompt.

We are beginning implementation of the BidRadar platform.
Read:
docs/project-vision.md
docs/product-requirements.md
docs/architecture.md
docs/database-schema.md
docs/api-specification.md
docs/design-system.md
docs/master-build-prompt.md
Do not build any features yet.
Your task is to verify the development environment.
Confirm:
- folder structure
- backend project
- frontend project
- Docker configuration
- environment variables
- Git structure
- dependency management
Recommend improvements if necessary.
Do not generate application functionality.
Do not change the architecture.
Only verify the project foundation.

Validation Checklist

Before continuing to Part 10 verify:

• Git repository exists.
• Monorepo structure created.
• Backend folder exists.
• Frontend folder exists.
• Documentation folder exists.
• Docker folder exists.
• Infrastructure folder exists.
• Scripts folder exists.
• Tests folder exists.
• Python virtual environment works.
• FastAPI installed.
• React application created.
• TypeScript enabled.
• Docker installed.
• PostgreSQL container running.
• Redis container running.
• .gitignore created.
• .env.example created.
• README.md created.
• Backend health endpoint responds.
• Frontend starts successfully.
• Initial Git commit completed.

Definition of Done

Part 9 is complete when:

• A clean BidRadar monorepo exists.
• Backend and frontend start successfully.
• Docker infrastructure is operational.
• Environment variables are documented.
• Development tooling is configured.
• Git version control is initialized.
• The repository is ready for feature implementation.
• Google AI Studio has a stable project foundation to build upon.

Recommended Git Commits

chore: initialize BidRadar monorepo

chore: configure backend development environment

chore: configure frontend development environment

chore: add Docker infrastructure

What We Built

In this article, we created the foundation on which the entire BidRadar platform will be developed.

Rather than generating business functionality immediately, we established a professional monorepo with a clear folder structure, isolated backend and frontend projects, Docker-based infrastructure, environment-variable management, Git version control, and local development tooling.

This foundation will support every feature added in the remainder of the series and provides Google AI Studio with a clean, predictable project to extend.

Next Article

Part 10 — Creating the FastAPI Backend Foundation

With the development environment complete, we can begin building the actual backend.

In Part 10, we will create:

• The FastAPI application structure
• Application configuration
• Settings management
• Dependency injection
• API router registration
• Health and readiness endpoints
• Logging configuration
• Exception handling
• Application startup and shutdown events
• Initial project modules

By the end of Part 10, BidRadar will have a production-ready FastAPI foundation that every future backend feature will build upon.