Skip to content

GitHub Pages Implementation Plan

Last updated: 2024-12-24

This document tracks implementation items for the Tax Practice AI documentation site.

Overview

The documentation site serves two audiences:

Site Path Audience Purpose
Technical Hub /index.html Internal team, developers Documentation navigation, implementation status
Client Portal /client_facing_docs/index.html Stakeholders, prospective clients Professional overview, progress visibility

Hosting: Cloudflare Pages (not GitHub Pages - provides access control) URL: https://ali-ai-acctg.pages.dev

Hosting Setup (Cloudflare)

GP-000: Cloudflare Pages + Access

Status: In Progress Completed: 2024-12-23

  • Create Cloudflare account
  • Connect GitHub repo to Cloudflare Pages
  • Configure build settings (output: /docs)
  • Set up Access policy for internal team (full site)
  • Set up Access policy for clients (path: /client_facing_docs only)
  • Test access with incognito window

Access Policies:

Application Path Who Can Access
Tax Practice AI Docs / (all) Internal team emails
Tax Practice AI - Client Portal /client_facing_docs Client/stakeholder emails (TODO)

Phase 1: Initial Setup

GP-001: Technical Hub (docs/index.html)

Status: Complete Completed: 2024-12-23 Priority: P0

  • Dark theme matching requirements_status.html
  • Header with project name and tagline
  • Implementation status summary cards:
  • Sequences complete (1/18)
  • Requirements implemented (25/325)
  • Tests passing (232)
  • Stories complete (10/82)
  • Current focus banner
  • Document navigation by category:
  • Technical Specifications
  • Security & Integration
  • Planning
  • Operations
  • Implementation Guides
  • Requirements
  • Interactive Pages section (Requirements Status, Presentation)
  • Sequence progress tracker (S1-S18)
  • Link to Client Portal
  • Footer with last updated date

GP-002: Client Portal (docs/client_facing_docs/index.html)

Status: Complete Completed: 2024-12-23 Priority: P0

  • Professional light theme (accounting firm aesthetic)
  • Navigation header with logo
  • Hero section with value proposition
  • Stakeholder-friendly progress section:
  • Visual timeline (Foundation → Client Portal → Documents → Tax Prep → Launch)
  • Milestone cards with badges (Complete, In Progress)
  • Plain English status (not requirement IDs)
  • Stats banner (232 tests, 100% quality, 7+ year retention, IRS compliant)
  • Link to Tax Practice AI Presentation
  • System highlights:
  • AI-powered document processing
  • Bank-level security
  • IRS compliance built-in
  • 7-year document retention
  • Industry integration
  • Real-time tracking
  • Resources section
  • Footer with professional branding and link to Technical Hub

Phase 2: Status Data Externalization

GP-003: Status JSON File

Status: Not Started Priority: P1

  • Create docs/status.json with current metrics
  • Structure for easy updates: 
    {
  "lastUpdated": "2024-12-23",
  "sequences": { "complete": 2, "total": 18 },
  "requirements": { "complete": 25, "total": 325 },
  "tests": { "passing": 232, "failing": 0 },
  "currentFocus": "Sequence 2: Client Management"
}
  • Update index.html to read from JSON
  • Update client portal to read from JSON
  • Document update process in RUNBOOK.md

GP-004: Milestone Definitions

Status: Not Started Priority: P1

  • Define stakeholder-visible milestones
  • Map sequences to milestones: | Milestone | Sequences | Description | |-----------|-----------|-------------| | Foundation | S1 | Core infrastructure ready | | Client Ready | S2-S4 | Client onboarding functional | | Document Flow | S5-S7 | Full document lifecycle | | Tax Season Ready | S8-S12 | Return preparation complete | | Production | S13-S18 | Full system operational |
  • Add milestone progress to status.json

Phase 3: Enhanced Features

GP-005: Sequence Detail Pages

Status: Not Started Priority: P2

  • Template for sequence status page
  • Auto-link from main status dashboard
  • Show stories within sequence
  • Requirements mapped to each story

GP-006: Interactive Progress Visualization

Status: Not Started Priority: P2

  • Timeline visualization with D3.js or Chart.js
  • Click-through to sequence details
  • Mobile-responsive design

GP-007: Automated Status Updates

Status: Not Started Priority: P3

  • GitHub Action to parse USER_STORIES.md
  • Extract completion status
  • Update status.json automatically
  • Trigger on push to main

Document Inventory

Documents to link from GitHub Pages:

Document Path Description
ARCHITECTURE.md docs/ARCHITECTURE.md System design and patterns
DATABASE_SCHEMA.sql docs/DATABASE_SCHEMA.sql PostgreSQL schema (35 tables)
API_SPECIFICATION.md docs/API_SPECIFICATION.md REST API contract
DATA_MODEL.md docs/DATA_MODEL.md Logical data model with ER diagrams
SECURITY_DESIGN.md docs/SECURITY_DESIGN.md Security architecture
INTEGRATION_CONTRACTS.md docs/INTEGRATION_CONTRACTS.md External service integrations
PROCESS_FLOWS.md docs/PROCESS_FLOWS.md State machines and workflows
PATTERNS.md docs/PATTERNS.md Code patterns and conventions
Document Path Description
USER_STORIES.md docs/USER_STORIES.md 82 prioritized stories
backlog.md docs/backlog.md Priority tracking
NEXT_STEPS.md docs/NEXT_STEPS.md Immediate action items
MIGRATION_REQUIREMENTS.md docs/MIGRATION_REQUIREMENTS.md Data migration spec
Document Path Description
RUNBOOK.md docs/RUNBOOK.md Operational procedures
Document Path Description
SEQUENCE_01_FOUNDATION.md docs/implementation/SEQUENCE_01_FOUNDATION.md Foundation sequence
SEQUENCE_02_CLIENT_IDENTITY.md docs/implementation/SEQUENCE_02_CLIENT_IDENTITY.md Client management sequence
Page Path Description
Requirements Status docs/requirements_status.html Detailed implementation status
Presentation docs/client_facing_docs/Tax_Practice_AI_Presentation.html System overview presentation

Style Guide

Technical Hub (Dark Theme)

--bg-primary: #1a1a2e;
--bg-secondary: #16213e;
--bg-card: #0f3460;
--accent: #e94560;
--accent-green: #00d26a;
--accent-yellow: #ffc107;
--accent-blue: #4da8da;
--text-primary: #eaeaea;
--text-secondary: #b8b8b8;

Client Portal (Light Professional Theme)

--bg-primary: #ffffff;
--bg-secondary: #f8fafc;
--bg-card: #ffffff;
--accent-primary: #1e3a5f;    /* Navy blue */
--accent-secondary: #2d5a87;  /* Lighter navy */
--accent-success: #059669;    /* Professional green */
--text-primary: #1a202c;
--text-secondary: #4a5568;
--border: #e2e8f0;

Cross-Session Coordination

These items may be updated by other sessions working on the source documents:

Document Updates Needed Owner Session
requirements_status.html Sync when requirements complete Status updates
USER_STORIES.md Story completion tracking Implementation sessions
ARCHITECTURE.md Version number, section updates Architecture sessions
status.json (future) Metrics updates Any implementation session

Protocol: When completing work that affects status metrics, update status.json (once created) or note in commit message for manual sync.

Notes

  • GitHub repo: dmccarty-ali/ali-ai-acctg
  • Site URL: https://ali-ai-acctg.pages.dev (Cloudflare Pages)
  • Access Control: Cloudflare Zero Trust (email-based authentication)
  • All markdown documents link to GitHub blob view (not raw)
  • HTML pages served directly from Cloudflare Pages

Next Session

Resume from GP-000: Create client-facing Access policy in Cloudflare Zero Trust: 1. Access controls → Applications → Add application → Self-hosted 2. Name: "Tax Practice AI - Client Portal" 3. Domain: ali-ai-acctg.pages.dev, Path: client_facing_docs 4. Policy: Allow specific client emails