Categories Full Stack App (React TS + FastAPI) — Dev Containers with Compose

Overview

A full-stack web application for managing hierarchical categories, designed with SOLID and MACH principles implementing optimistic UI and retry logic.

Frontend

• React + TypeScript: React has a strong developer community, enables modularization and high performance. TS prevents runtime bugs.
• Vite: fast development server/build tool which supports typescript and jsx.
• React Router: Declarative client-side navigation.
• TanStack Query (React Query): async state management - needed for optimistic UI.
• Material UI (MUI): Accessible and consistent design system with theming.
• rc-tree: enables tree visualization with drag and drop feature.

Backend

• FastAPI: modern async API development with python, fast to deploy, high performance, rich amount of in-built features like routing etc.
• Pydantic: request/response validation, enforce typing.
• psycopg v3: Postgres driver with connection pooling.

Infrastructure

• Docker + Docker Compose: reproducible and isolated environments
• .env files: externalized configurations

---

Assumptions Made

• Database is already provided in a container at postgres:5432.
• Single-tenant POC
• Only essential API endpoints (GET, PATCH) are in scope.
• Development focus is on functionality & UX

---

Known Limitiations and Bugs

• Fallback UI in case of 5xx error from API service is incorect, shows 'Loading...' while it must be displaying a helpful error message. Most likely cause: error is getting swallowed by fetchCategories function (frontend\src\api\categories.ts: line 4). Reproduced by shutting off postgres or backend containers.
• Similarly in case of timeout, need to add logic to display informative message
• Database side detection of cyclic relationships is costly at scale, at bigger scale would need a different solution like a closure table

---

Setup, Build and Run with Docker Compose

1) Configure environment

Edit backend/.env if needed (default points to postgres:5432).

2) Build and run

docker compose build
docker compose up -d

• Frontend: http://localhost:5173
• API: http://localhost:8000/api/v1/categories
• Postgres: http://localhost:5432

API

• GET /api/v1/categories → [{ id, name, description, parent_id }]
• PATCH /api/v1/categories/{id} body { parent_id: number|null } → 200 with updated object

Errors: 400 bad body, 404 not found, 409 cycle detected, 422 self-parent, 500 server error.

Path to Production

• UI & UX: resolve bugs when backend/database services are down, currently displayed message is not informative. Make the application look more modern.
• Security & Access: Identity & Access Control, CORS, CSRF, XSS, DDoS Mitigation (rate limit, throttle), secret management, encryption at rest and in transit
• Reliability & Reslience: Backpressure, concurrency handling
• Performance & Scalability: Caching, queues and pagination if data grows larger, replace recursive query for cyclic relationship detection with closure table. Lazy loading/api calls with graphQL of only expanded categories
• Obeservability & Monitoring: logging, tracing and auditing
• Testing: unit testing, integration/contract testing, e2e, load
• Real-Time & Data Freshness: add websocket/webhook to track changes to database if need super fresh data, relevant especially if multi-tenant