Project Documentation

1. Overview

Chalukya Tiles is a full-stack showroom website for floor tiles and interior tiles. It is designed to feel premium and minimal while remaining fast, maintainable, and free of heavy frontend frameworks.

The backend (FastAPI) renders HTML with Jinja2 and exposes JSON APIs for contact and product enquiries. The frontend is modular CSS and vanilla JavaScript — ideal for a brochure-style business site with light interactivity.

2. Why this project is useful

Compared with a generic page builder site, this codebase is transparent: every animation, form field, and API route is owned by you and can be audited or customized without fighting a theme marketplace.

3. Tech stack

Not used (by design): React, Vue, Angular, Bootstrap, jQuery, or heavy UI kits.

4. Architecture

Request flow at a high level:

Design principles

• Server-rendered pages for SEO and first paint simplicity.
• Modular assets — one CSS/JS concern per file.
• Isolated data layer — swap SQLite connection later without rewriting routes.
• Progressive enhancement — content works without heavy JS; JS adds polish and forms.
• Security defaults — nosniff, frame options, referrer and permissions policies.

5. Folder structure

website_tiles1/
├── PROJECT_MEMORY.md      # Permanent session memory
├── app.py                 # FastAPI app, pages, SEO, 404
├── requirements.txt
├── README.md
├── templates/             # HTML (Jinja2)
├── static/css|js|images|videos|icons
├── api/enquiry.py         # JSON API routers
├── database/db.py         # SQLite schema & helpers
└── assets/                # Non-public brand sources

Public URLs under /static/… map to the static/ folder. Source design files (logo masters, raw video) belong in assets/, not in the public web root.

6. Features

• Mobile-first responsive layout (Flexbox + CSS Grid)
• Premium theme: white, charcoal, stone grey, warm gold
• Sticky navbar — transparent over hero, solid on scroll / inner pages
• Hamburger drawer with keyboard Escape and focus handling
• Hero video (optional) + typing headline + parallax layer
• Animated counters, scroll reveals, button ripples, loading screen
• Product catalogue with 9 category filters + deep links
• Masonry gallery, lightbox (image/video), keyboard navigation
• Testimonials with star ratings and animated cards
• Contact form + product enquiry with client validation and Fetch API
• SQLite persistence of leads
• Floating WhatsApp + scroll-to-top
• Newsletter UI (client-side thank-you feedback)
• Branded 404 page
• robots.txt, sitemap.xml, home JSON-LD

7. Website pages

Product enquire buttons navigate to /contact?product=Name&category=Category, which switches the form to POST /api/enquiry.

8. Frontend system

CSS modules

• main.css — design tokens, reset, buttons, cards, forms, about/testimonials, utilities
• navbar.css / footer.css — site chrome
• hero.css — homepage hero and home sections
• products.css, gallery.css, contact.css — page features
• animations.css — scroll reveals, image wipe, typing caret

JavaScript modules

• main.js — loader, scroll-top, ripple, Intersection Observer, counters, typing, parallax, product filters, newsletter, year
• navbar.js — scroll solid state, mobile drawer
• slider.js — reviews carousel + hero video boot
• gallery.js — gallery filters + accessible lightbox
• contact.js — validation + submit
• api.js — window.ChalukyaAPI Fetch helpers

Scripts load with defer. Prefer data-attributes (e.g. data-animate, data-slider) over hard-coded IDs for reuse.

9. Backend system

app.py is the single process entry:

• Lifespan hook runs init_db()
• Mounts /static
• Registers HTML page routes via render_page()
• Includes enquiry_router from api/enquiry.py
• Serves /robots.txt, /sitemap.xml
• Custom HTML 404 for non-API paths
• Security headers middleware

Shared template context includes brand_name, brand_tagline, page_title, active_page, and site_url (from SITE_URL constant).

10. API reference

Example contact payload

{
  "name": "Jane Doe",
  "phone": "99407 18307",
  "email": "jane@example.com",
  "message": "Looking for bathroom tiles for a renovation."
}

Example success response

{
  "success": true,
  "message": "Thank you! Your message has been received. We will contact you shortly.",
  "id": 1
}

Invalid bodies return 422 with FastAPI validation details. Client form maps field errors when possible.

11. Database

File: database/showroom.db (created automatically; gitignored).

Tables

• contact_messages — general form submissions
• enquiries — product/showroom enquiries with optional product fields

Both store ISO-8601 UTC created_at and a status defaulting to new for future admin workflows. List helpers exist in database/db.py but no admin UI yet.

MySQL later

1. Recreate tables with MySQL types (DATETIME, AUTO_INCREMENT).
2. Replace get_connection() only.
3. Keep insert column names stable so routes stay unchanged.

12. SEO & accessibility

SEO

• Per-page <title> and meta description
• Open Graph basics on main pages
• Home JSON-LD (HomeAndConstructionBusiness)
• /robots.txt and /sitemap.xml (set real SITE_URL)
• Semantic landmarks and heading hierarchy

Accessibility

• Skip link to #main
• ARIA labels on icon buttons and drawers
• Focus-visible outlines
• Lightbox focus trap + Escape / arrows
• Form errors with aria-invalid and live status
• prefers-reduced-motion disables non-essential motion

13. Admin panel (v1.5.0)

Private operations console at /admin (login at /admin/login). Default credentials: admin / chalukya@2026 (override with env ADMIN_USERNAME, ADMIN_PASSWORD, ADMIN_SECRET).

• Dashboard — sales totals, leads, queries, customers, media counts
• Tile Media — upload image + name, model number, colour, material category (optional size/finish/description). Shown on Products, Gallery, and Home featured.
• Collection Videos — upload MP4/WebM (+ optional poster). Active videos render mid-down on the homepage (below trust strip).
• Sales / Leads / Customers — CRUD tables for analytics and CRM-lite data
• Queries — contact form messages + product enquiries with status updates

Uploads land in static/uploads/{tiles,videos,posters}/. Schema lives in database/db.py; API in api/admin.py.

14. Setup & run (Windows)

cd C:\Users\Admin\Downloads\ChalukyaTiles_website\website_tiles1
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
uvicorn app:app --reload --host 127.0.0.1 --port 8000

Open http://127.0.0.1:8000 — admin at http://127.0.0.1:8000/admin — documentation at http://127.0.0.1:8000/docs. Interactive API docs at /api/docs.

15. Customize & launch checklist

1. Change admin password (env vars or re-seed after deleting admin row).
2. Update phone, email, WhatsApp links, address, map embeds.
3. Set SITE_URL / ADMIN_SECRET for production.
4. Upload real tile photos and collection videos via Admin → Tile Media / Videos.
5. Back up database/showroom.db and static/uploads/ on a schedule.
6. Serve behind HTTPS reverse proxy in production.

16. Recommended next extensions

• Email notify — send mail on new submission.
• MySQL — production multi-instance DB.
• Role-based admin — multiple staff accounts with permissions.
• i18n — language switch if needed for bilingual markets.

17. Project memory workflow

File: PROJECT_MEMORY.md (project root). After every module or coding session:

1. Create the file if missing; otherwise update it.
2. Record overview, stack, structure, architecture, completed/pending work, files, APIs, DB changes, TODO, next task, version.
3. Never wipe useful history — append session notes.
4. Refresh the CONTINUE PROMPT section so a new chat can resume instantly.
5. Keep this /docs page aligned when architecture changes.

Visit homepage Open API Swagger Contact form