How ishant-kb/grocery-management-system works
1. Overall shape
- This repo is a two-tier full-stack web application for grocery management.
- The architecture is split cleanly into a Next.js frontend and a FastAPI backend with a separate persistence layer implied by SQLAlchemy/Alembic/PostgreSQL.
2. Frontend boundary
- frontend/ is the user-facing client.
- It uses the Next.js App Router structure (app/layout.tsx, app/page.tsx) with React and TypeScript.
- globals.css indicates a single global styling entrypoint, with Tailwind CSS configured through the standard Next/PostCSS setup.
3. Frontend responsibilities
- The frontend owns page rendering, UI composition, and browser-side interaction.
- Because there are only core app files in the tree, this looks like a thin presentation layer rather than a monorepo with shared UI packages or complex client-side subsystems.
4. Backend boundary
- backend/ is the API server.
- backend/app/main.py is the application entrypoint, and backend/app/db/database.py is the only visible infrastructure module, so the backend is currently centered around bootstrapping and database connectivity.
5. Backend responsibilities
- The backend exposes HTTP endpoints via FastAPI and serves as the system of record access layer.
- The README confirms the root endpoint returns a simple health response, which suggests the backend is still in an early scaffold phase and not yet showing feature-specific domain modules in the tree.
6. Persistence layer
- The backend is prepared for relational storage through SQLAlchemy and PostgreSQL (psycopg2-binary).
- alembic.ini shows migration management is part of the architecture, so schema changes are intended to be tracked independently from application code.
7. Data flow
- The expected request path is: browser → Next.js frontend → FastAPI backend → PostgreSQL.
- The frontend likely calls the backend over HTTP, and the backend translates those requests into database reads/writes through SQLAlchemy.
- No shared runtime or server-side rendering dependency between frontend and backend is visible in the tree.
8. Operational/runtime split
- The backend runs under Uvicorn, which is the ASGI server for FastAPI.
- The frontend runs via the Next.js dev server.
- The README documents separate local ports: frontend on 3000, backend on 8000, reinforcing the independent deployment/runtime boundary.
9. Authentication and security foundations
- The backend dependencies include python-jose, passlib[bcrypt], and pydantic[email], which indicates the system is being built with authentication, password hashing, and validated user/contact data in mind.
- Even though auth routes/models are not visible in the file tree, these libraries are part of the intended backend capability set.
10. Repository maturity
- The frontend appears more scaffolded than feature-rich, while the backend is even more foundational with only the main app and DB connection visible.
- For an architecture diagram, it is accurate to show presentation layer, API layer, and database layer, but not to assume additional services, queues, or microservices that are not present here.
11. What to draw explicitly
- Show two deployable units: frontend app and backend API.
- Show the backend connecting to a PostgreSQL database via SQLAlchemy.
- Show Alembic as a supporting migration path for schema evolution.
- Mark the frontend/backend link as HTTP API calls.
Main entry points: main.py FastAPI App · requirements.txt Backend Stack · layout.tsx Layout · database.py DB Module
Components 14
Frontend
Next.js presentation layer and browser UI
- App Router · Next.js application shell and page composition
- Layout · Top-level document and shared UI frame
frontend/app/layout.tsx - Home Page · Primary route rendered by the frontend
frontend/app/page.tsx - Global CSS · Single global styling entrypoint
frontend/app/globals.css - Next Config · Next.js runtime and build configuration
frontend/next.config.ts
Backend
FastAPI application and API runtime
- FastAPI App · ASGI application entrypoint and request handler
backend/app/main.py - Backend Stack · Application dependency set for API, auth, and data access
backend/requirements.txt - DB Module · Database connection and session setup
backend/app/db/database.py
Persistence
Database and schema management
- SQLAlchemy · Relational data access layer used by the backend
- Migrations · Database migration workflow for schema evolution
backend/alembic.ini - PostgreSQL · Relational system of record
Runtime
External execution boundaries
- Browser · User-facing runtime that loads the web app
- HTTP API · HTTP contract between client and server
- Uvicorn · Server used to run the FastAPI application
Connections 15
- Browser → App Router: loads UI · Browser opens the Next.js client
- App Router → Layout: renders shell · App Router composes the shared document frame
- App Router → Home Page: renders route · App Router serves the main page
- Layout → Global CSS: applies styles · Layout pulls in the global stylesheet
- App Router → Next Config: build/runtime · Next.js behavior is shaped by the project config
- App Router → HTTP API: HTTP calls · Frontend issues requests to the backend API
- HTTP API → FastAPI App: requests · HTTP traffic reaches the FastAPI entrypoint
- FastAPI App → Uvicorn: served by · FastAPI runs under Uvicorn
- Backend Stack → FastAPI App: enables · Dependencies support the API application
- Backend Stack → SQLAlchemy: includes · Dependency set includes the ORM stack
- FastAPI App → DB Module: uses DB · API entrypoint relies on database connectivity
- DB Module → SQLAlchemy: through ORM · Database access is mediated by SQLAlchemy
- SQLAlchemy → PostgreSQL: stores data · ORM reads and writes the PostgreSQL database
- Migrations → PostgreSQL: migrates schema · Alembic manages database schema changes
- FastAPI App → Migrations: schema evolution · Backend is organized to evolve the database independently