ShopDB Documentation

Welcome to the ShopDB documentation! This folder contains everything you need to understand, develop, and maintain the ShopDB application.

---

Documentation Overview

📘 For New Team Members

Start here in this order:

1. QUICK_REFERENCE.md ⭐ START HERE

   • Quick facts, common tasks, cheat sheets
   • Perfect for daily reference
   • Time to read: 15 minutes

2. GIT_WORKFLOW.md 🔧 MANDATORY

   • Git workflow and commit standards
   • How to commit and push changes
   • MUST READ before making any code changes
   • Time to read: 20 minutes

3. ASP_DEVELOPMENT_GUIDE.md

   • Development environment setup
   • How to start/stop the dev environment
   • VBScript/ASP basics and patterns
   • Time to read: 30 minutes

4. DEEP_DIVE_REPORT.md 📚 COMPREHENSIVE

   • Complete database schema documentation
   • Application architecture deep dive
   • Data flows and workflows
   • Technical debt analysis
   • Recommendations and roadmap
   • Time to read: 2-3 hours (reference material)

5. STANDARDS.md ⚠️ MANDATORY

   • Coding standards (MUST follow)
   • Security requirements
   • Database access patterns
   • Input validation rules
   • Error handling standards
   • Time to read: 45 minutes

6. NESTED_ENTITY_CREATION.md

   • How to create complex forms
   • Nested entity management (e.g., add printer + create new model inline)
   • Time to read: 20 minutes

7. GIT_SETUP_GUIDE.md

   • Setting up Gitea (Git server with web UI)
   • SSH key configuration
   • First-time Git setup
   • Time to read: 30 minutes (one-time setup)

8. GITEA_FEATURES_GUIDE.md

   • Using Gitea Projects (Kanban boards)
   • Issue tracking and bug management
   • Wiki for collaborative documentation
   • Pull requests and code review
   • Milestones and releases
   • Time to read: 45 minutes

---

Quick Navigation

By Role

Developers:

1. Read: QUICK_REFERENCE.md
2. MANDATORY: GIT_WORKFLOW.md ⚠️
3. Setup: ASP_DEVELOPMENT_GUIDE.md, GIT_SETUP_GUIDE.md
4. Standards: STANDARDS.md
5. Deep dive: DEEP_DIVE_REPORT.md (sections 2, 3, 6)
6. Advanced: NESTED_ENTITY_CREATION.md
7. Project Management: GITEA_FEATURES_GUIDE.md

Database Administrators:

1. Read: QUICK_REFERENCE.md (Database section)
2. Read: DEEP_DIVE_REPORT.md (Section 1: Database Architecture)
3. Review: STANDARDS.md (Database Access Standards)
4. Reference: SQL queries in QUICK_REFERENCE.md

System Administrators:

1. Read: ASP_DEVELOPMENT_GUIDE.md (Prerequisites, Troubleshooting)
2. Read: DEEP_DIVE_REPORT.md (Section 7.3: For System Administrators)
3. Reference: QUICK_REFERENCE.md (Common Tasks)

Business Analysts:

1. Read: DEEP_DIVE_REPORT.md (Executive Summary, Section 1, Section 7.4)
2. Reference: QUICK_REFERENCE.md (Key Views, SQL Queries)

Project Managers:

1. Read: DEEP_DIVE_REPORT.md (Executive Summary, Section 4: Technical Debt, Section 6: Recommendations)
2. Read: GITEA_FEATURES_GUIDE.md (Projects, Issues, Milestones, Releases)

---

By Topic

Database

• Schema Overview: DEEP_DIVE_REPORT.md → Section 1
• Quick Reference: QUICK_REFERENCE.md → Core Tables Cheat Sheet
• Access Patterns: STANDARDS.md → Database Access Standards
• Views: DEEP_DIVE_REPORT.md → Section 1.3
• Sample Queries: QUICK_REFERENCE.md → Useful SQL Queries

Development

• Git Workflow: GIT_WORKFLOW.md → Complete workflow guide ⚠️ MANDATORY
• Git Setup: GIT_SETUP_GUIDE.md → Gitea installation and SSH keys
• Project Management: GITEA_FEATURES_GUIDE.md → Issues, Projects, Wiki, PRs
• Setup Environment: ASP_DEVELOPMENT_GUIDE.md → Project Setup
• Coding Patterns: ASP_DEVELOPMENT_GUIDE.md → Common VBScript/ASP Patterns
• Standards: STANDARDS.md → All sections
• Quick Reference: QUICK_REFERENCE.md → Key VBScript Patterns

Architecture

• Overview: DEEP_DIVE_REPORT.md → Section 2
• File Structure: DEEP_DIVE_REPORT.md → Section 2.2
• Data Flows: DEEP_DIVE_REPORT.md → Section 3
• Diagrams: DEEP_DIVE_REPORT.md → Sections 9, 10

Security

• Standards: STANDARDS.md → Security Standards
• Issues: DEEP_DIVE_REPORT.md → Section 4.1
• Checklist: QUICK_REFERENCE.md → Security Checklist

Troubleshooting

• Dev Environment: ASP_DEVELOPMENT_GUIDE.md → Troubleshooting
• Quick Fixes: QUICK_REFERENCE.md → Troubleshooting
• Common Issues: DEEP_DIVE_REPORT.md → Section 4

---

Document Maintenance

When to Update

QUICK_REFERENCE.md:

• New common task identified
• New frequently-used query
• New troubleshooting tip

ASP_DEVELOPMENT_GUIDE.md:

• Development environment changes
• New tools or dependencies
• Setup process changes

DEEP_DIVE_REPORT.md:

• Major schema changes
• New features added
• Architecture changes
• Quarterly review updates

STANDARDS.md:

• New coding standards adopted
• Security policy changes
• New validation patterns
• New error codes

NESTED_ENTITY_CREATION.md:

• New nested entity patterns
• Complex form examples

How to Update

1. Small Updates: Edit the file directly, commit to Git (once setup)
2. Major Updates: Create a copy, edit, have peer review, then replace
3. Always Update: "Last Updated" date at bottom of each file
4. Document Changes: Note what changed in Git commit message

---

Document Status

Document	Last Updated	Status	Review Cycle
QUICK_REFERENCE.md	2025-10-20	✅ Current	As needed
GIT_WORKFLOW.md	2025-10-20	✅ Current	Quarterly
GIT_SETUP_GUIDE.md	2025-10-20	✅ Current	Annually
GITEA_FEATURES_GUIDE.md	2025-10-20	✅ Current	Quarterly
ASP_DEVELOPMENT_GUIDE.md	2025-10-10	✅ Current	Quarterly
DEEP_DIVE_REPORT.md	2025-10-20	✅ Current	Quarterly
STANDARDS.md	2025-10-10	✅ Current	Semi-annually
NESTED_ENTITY_CREATION.md	2025-10-10	✅ Current	Annually
README.md (this file)	2025-10-20	✅ Current	As needed

---

Quick Start for New Developers

Day 1 Checklist

• Read QUICK_REFERENCE.md (15 min)
• Read GIT_WORKFLOW.md (20 min) - MANDATORY ⚠️
• Follow ASP_DEVELOPMENT_GUIDE.md to setup environment (1-2 hours)
• Verify Git repository is initialized
• Browse application at http://192.168.122.151:8080
• Read STANDARDS.md (45 min)
• Make a test edit, commit, and push to Git

Week 1 Checklist

• Read DEEP_DIVE_REPORT.md Executive Summary
• Read DEEP_DIVE_REPORT.md Section 1 (Database)
• Read DEEP_DIVE_REPORT.md Section 2 (Architecture)
• Read GITEA_FEATURES_GUIDE.md (Issues, Projects, Wiki)
• Create your first issue in Gitea
• Explore all display*.asp pages
• Run sample SQL queries from QUICK_REFERENCE.md
• Understand PC-to-machine assignment logic

Month 1 Checklist

• Complete DEEP_DIVE_REPORT.md
• Implement a small feature end-to-end
• Review NESTED_ENTITY_CREATION.md
• Contribute a documentation improvement
• Pair program with experienced team member

---

External Resources

Classic ASP / VBScript

• Microsoft ASP Reference
• VBScript Language Reference
• W3Schools ASP Tutorial

MySQL

• MySQL 5.6 Reference Manual
• MySQL FULLTEXT Search
• MySQL Performance Tuning

Frontend

• Bootstrap 4.6 Documentation
• jQuery Documentation
• Material Design Iconic Font
• FullCalendar v3
• DataTables

---

Getting Help

Documentation Issues

• Document unclear? Create an issue or update it yourself!
• Found an error? Fix it and commit
• Missing information? Add it!

Technical Questions

• Check QUICK_REFERENCE.md first
• Search DEEP_DIVE_REPORT.md
• Ask team lead
• Create documentation if answer isn't documented

Code Questions

• Review STANDARDS.md
• Check ASP_DEVELOPMENT_GUIDE.md for patterns
• Look at similar existing code
• Ask for code review

---

Contributing to Documentation

We encourage all team members to improve documentation!

Guidelines

1. Be Clear - Write for someone who doesn't know the system
2. Be Concise - Respect the reader's time
3. Be Accurate - Test commands/code before documenting
4. Be Current - Update dates when you edit
5. Be Helpful - Include examples and context

What to Document

• Solutions to problems you encountered
• Common tasks you perform
• Tricky patterns or gotchas
• New features or changes
• Helpful queries or scripts

How to Contribute

1. Edit the relevant .md file
2. Update "Last Updated" date
3. Commit with descriptive message
4. (Optional) Have peer review for major changes

---

Version History

v1.3 - 2025-10-20

• Added GIT_WORKFLOW.md (mandatory Git workflow documentation)
• Added GIT_SETUP_GUIDE.md (Gitea setup guide)
• Updated README.md with Git workflow references
• Established mandatory commit-after-every-change policy

v1.2 - 2025-10-20

• Added DEEP_DIVE_REPORT.md (comprehensive technical report)
• Added QUICK_REFERENCE.md (cheat sheets)
• Added this README.md
• Updated ASP_DEVELOPMENT_GUIDE.md with documentation references

v1.1 - 2025-10-10

• Added STANDARDS.md (coding standards)
• Added NESTED_ENTITY_CREATION.md
• Updated ASP_DEVELOPMENT_GUIDE.md

v1.0 - 2025-10-09

• Initial ASP_DEVELOPMENT_GUIDE.md created

---

Future Documentation Plans

• API Documentation (when APIs expand)
• Deployment Guide (CI/CD pipeline)
• Security Audit Report
• Performance Optimization Guide
• Testing Guide (when tests implemented)
• Video tutorials (screen recordings)
• FAQ document
• Glossary of GE-specific terms

---

Maintained By: Development Team Questions? Ask team lead or update docs directly Feedback? Create issue or improve the docs yourself!

---

Summary

You now have comprehensive documentation covering:

✅ Quick Reference - Daily cheat sheet ✅ Git Workflow - Mandatory version control workflow ⚠️ ✅ Development Guide - Environment setup ✅ Deep Dive Report - Complete technical documentation ✅ Standards - Mandatory coding rules ✅ Advanced Patterns - Complex forms

Start with QUICK_REFERENCE.md, then read GIT_WORKFLOW.md before making any code changes!

Happy coding! 🚀