Roman Imankulov imankulov

Client-server architecture guidelines

Use these guidelines when adding a typed React frontend to a Python project that already has useful server-side behavior but little or no UI. The Smello project is the reference shape: one repository, one Python server, one TypeScript client, and the server's OpenAPI schema as the source of truth for shared types.

The exact directory names can change. The contract should not.

Overall architecture

Use a monorepo with separate server and frontend packages.

Problem: FastAPI doesn't accept JSON-encoded pydantic models in query strings. See #884.

Solution: Use json_param() from the snippet below.

Usage example.

from fastapi import FastAPI
from pydantic import BaseModel

Who is your craziest/most interesting relative?
What’s a weird fact you happen to know?
What’s your strangest talent?
Everyone has those recurring bad dreams … what is your nightmare?
What is your favorite smell and why?
What completely safe animal are you inexplicably afraid of?
What do you pretend to hate but actually love?
If you had a boat, what would you name it?
What was your first job?
Have you ever met anyone famous?

	You are a powerful agentic AI coding assistant, powered by GPT-4o. You operate exclusively in Cursor, the world's best IDE.

	You are pair programming with a USER to solve their coding task.
	The task may require creating a new codebase, modifying or debugging an existing codebase, or simply answering a question.
	Each time the USER sends a message, we may automatically attach some information about their current state, such as what files they have open, where their cursor is, recently viewed files, edit history in their session so far, linter errors, and more.
	This information may or may not be relevant to the coding task, it is up for you to decide.
	Your main goal is to follow the USER's instructions at each message.

	<communication>
	1. Be conversational but professional.

	"""
	A simple contrived example of a FastAPI application that heavily uses
	the FastAPI dependency injection system.

	Sample request http://127.0.0.1:9876/tasks?user_id=123456
	returns [{"id":1,"name":"Task 1","user":{"id":123456,"name":"John Doe"}}]

	Dependency tree:

	get_me()

	import requests
	from requests.adapters import HTTPAdapter
	from urllib3.util.retry import Retry

	USER_AGENT = "My project (https://example.com)"


	def get_default_session() -> requests.Session:
	"""Return a request.Session() instance with reasonable defaults for retries.

	#!/usr/bin/env ipython -i
	import datetime
	import json
	from typing import Optional

	import sqlalchemy as sa
	from sqlalchemy.orm import declarative_base, sessionmaker
	from sqlalchemy.dialects.postgresql import JSONB

	from pydantic import BaseModel, Field, parse_obj_as

	menu=$(curl -s 'https://www.facebook.com/SambaNaGrelha' \| \
	rg -o 'Bom dia estimados clientes hoje para prato do dia temos.*?Fazemos entregas ao domicílio' \| \
	head -n1 \| html2text)
	curl -s "https://api.telegram.org/bot$BOT_ID/sendMessage?chat_id=$CHAT_ID" -d text="$menu" > /dev/null

	#!/usr/bin/env python
	"""
	An ad-hoc script to analyze the percentage of the topic-specific questions for
	each programming language.

	For each language, the script downloads two pages and looks for the number of questions
	in the title, like "NNN,NNN questions". For example, for "python" and
	an extra tag "architecture", the script downloads
	https://stackoverflow.com/questions/tagged/python and
	https://stackoverflow.com/questions/tagged/python+architecture.