User guide, architecture & build handbook

1. Project overview

Chalukya Tiles is a premium floor & interior tiles showroom website for a Coimbatore business. It is a full-stack marketing site with a private admin console for media, leads, sales, customers, and form queries.

2. How to run in VS Code

2.1 One-time setup

1. Open VS Code → File → Open Folder → select C:\Users\Admin\Downloads\ChalukyaTiles_website\website_tiles1
2. Open the integrated terminal: Ctrl + ` (backtick)
3. Run the commands in the next block (copy–paste into the terminal).

2.2 Terminal commands (copy–paste)

Use these in the VS Code terminal (PowerShell). Prefer calling the venv Python directly if activation is blocked.

# 1) Go to project folder
cd C:\Users\Admin\Downloads\ChalukyaTiles_website\website_tiles1

# 2) Create virtual environment (only if .venv is missing)
C:\Users\Admin\AppData\Local\Python\pythoncore-3.14-64\python.exe -m venv .venv

# 3) Install dependencies
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -r requirements.txt

# 4) Start the website (development with auto-reload)
.\.venv\Scripts\python.exe -m uvicorn app:app --reload --host 127.0.0.1 --port 8000

2.3 Alternative: activate venv then run

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

If PowerShell blocks activation:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

2.4 After the server starts

• Terminal shows: Uvicorn running on http://127.0.0.1:8000
• Open a browser → http://127.0.0.1:8000
• Stop server anytime: click the terminal, press Ctrl + C

2.5 Production-style run (no reload)

.\.venv\Scripts\python.exe -m uvicorn app:app --host 0.0.0.0 --port 8000 --workers 2

3. Important URLs

4. Tech stack (categorized)

4.1 Frontend

Strict exclusions: React, Vue, Angular, Bootstrap, jQuery — not used.

4.2 Backend

4.3 Database & storage

4.4 Tooling / platform

• Windows + VS Code compatible
• Virtual environment: .venv
• Dependencies: requirements.txt
• Project memory: PROJECT_MEMORY.md

5. Architecture

Browser (public visitors)
  │
  ├─ GET HTML pages ──► FastAPI (app.py) ──► Jinja2 templates/
  ├─ GET /static/*   ──► StaticFiles (CSS, JS, images, uploads)
  └─ POST /api/contact|enquiry ──► api/enquiry.py ──► database/db.py ──► SQLite

Browser (admin staff)
  │
  ├─ GET /admin/login, /admin ──► admin HTML + session cookie
  └─ /api/admin/* ──► api/admin.py ──► db + static/uploads/

Data flow (tile upload example)
  Admin form ─► multipart POST /api/admin/tiles
            ─► save file to static/uploads/tiles/
            ─► insert row into tiles table
            ─► public /products and /gallery render from DB

5.1 Design patterns used

• SSR pages — HTML generated on the server (fast first paint, good SEO)
• Modular CSS/JS — one file per feature area
• JSON APIs — forms and admin use Fetch + JSON/multipart
• Session auth — admin routes require logged-in cookie
• Repository helpers — all SQL in database/db.py

6. Folder structure

website_tiles1/
├── USER_GUIDE.html          ← this handbook (also at /user-guide)
├── PROJECT_MEMORY.md        ← permanent session memory
├── README.md
├── app.py                   ← FastAPI entry: pages, SEO, admin HTML routes
├── requirements.txt
├── api/
│   ├── enquiry.py           ← public contact / enquiry API
│   └── admin.py             ← admin login, CRUD, uploads
├── database/
│   ├── db.py                ← schema, helpers, seed admin + demo analytics
│   └── showroom.db          ← runtime SQLite (created on first run)
├── templates/               ← public + admin HTML pages
├── static/
│   ├── css/                 ← main, navbar, hero, products, gallery, admin, …
│   ├── js/                  ← main, navbar, gallery, contact, admin, …
│   ├── images/              ← default SVG placeholders
│   ├── icons/               ← logo, favicon
│   ├── videos/              ← optional hero showroom.mp4
│   └── uploads/             ← admin uploads (tiles, videos, posters)
└── assets/                  ← private brand sources (not public)

7. Public website — pages & uses

Visitor journey

1. Land on Home → explore collections / video
2. Browse Products → filter by category → Enquire
3. Contact form or enquiry → stored in SQLite → visible in Admin → Queries
4. Call / WhatsApp using site phone links

8. Admin panel guide

URL: /admin after login at /admin/login.

8.1 Dashboard

• Sales total & this month
• Leads count (and new)
• Queries total (contact + enquiries)
• Customers, tile media, videos
• Recent sales, leads, and queries tables

8.2 Tile Media (upload products)

Required fields when uploading a tile image:

• Tile name — display name (e.g. Carrara Luxe)
• Model number — e.g. CT-MRB-1200
• Colour — e.g. White / Grey
• Material category — Vitrified, Marble Finish, Bathroom, etc.
• Image file — JPG / PNG / WebP

Optional: size, finish, description. Tiles appear on Products, Concept Gallery, and Home featured (latest).

8.3 Collection Videos

• Upload MP4 / WebM (+ optional poster image)
• Set Active = Yes to show on homepage
• Placement: mid-down homepage — after trust counters, before Featured Products

8.4 Sales / Leads / Customers / Queries

9. Media & uploads

There is no public visitor upload. Only authenticated admin can upload media.

10. Data & analytics (what the admin tracks)

Demo sample sales/leads/customers are seeded on first DB init so the dashboard is not empty.

11. API reference (summary)

Public

Admin (login required)

12. Database schema (tables)

File: database/showroom.db · Logic: database/db.py · Auto-created on server start.

13. Frontend system

CSS modules (static/css/)

• main.css — tokens, layout, forms, about/testimonials
• navbar.css, footer.css, hero.css, products.css, gallery.css, contact.css, animations.css, docs.css, admin.css, user-guide.css

JS modules (static/js/)

• main.js — loader, scroll-top, animations, product filters
• navbar.js, slider.js, gallery.js, contact.js, api.js, admin.js

Theme tokens

• Primary white, navy secondary #0b1f4a, accent blue #2f7de1
• Fonts: Inter + Poppins

14. Security & SEO

• Security headers: X-Content-Type-Options, X-Frame-Options, Referrer-Policy, Permissions-Policy
• Admin session cookie (12h), password hashed with PBKDF2
• robots.txt disallows /admin
• Sitemap at /sitemap.xml — set real SITE_URL in app.py or env
• Home JSON-LD business schema
• Accessibility: skip link, ARIA, keyboard lightbox, reduced-motion

15. Brand details

16. Launch checklist

1. Change admin password / set ADMIN_SECRET
2. Set production SITE_URL
3. Upload real tile photos via Admin → Tile Media
4. Upload collection video(s) for homepage
5. Verify contact form & enquiries appear in Admin → Queries
6. Back up database/showroom.db and static/uploads/
7. Deploy behind HTTPS reverse proxy (Nginx / Caddy / IIS)

17. Troubleshooting

18. Version history (highlights)

Full history lives in PROJECT_MEMORY.md.