TypeCraft v2.0 - Architecture Overview

Last Updated: 2025-11-02 Status: 🚧 Under Active Development

📐 High-Level Architecture

┌───────────────────────────────────────────────────────────────┐
│                     USER INTERFACE                             │
│              (Next.js 16 + React 19 + Vercel)                 │
│                                                                │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
│  │   Dashboard  │  │   Editor     │  │  Export      │       │
│  │   (Projects) │  │   (Canvas)   │  │  (PDF/ePub)  │       │
│  └──────────────┘  └──────────────┘  └──────────────┘       │
│                                                                │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
│  │ AI Creative  │  │ Typography   │  │  Layout      │       │
│  │    Suite     │  │   Selector   │  │  Builder     │       │
│  └──────────────┘  └──────────────┘  └──────────────┘       │
└───────────────────────────────────────────────────────────────┘
                              │
                              │ HTTPS / WebSocket
                              ▼
┌───────────────────────────────────────────────────────────────┐
│                    API GATEWAY                                 │
│              (Go Gin Router + Cloud Run)                      │
│                                                                │
│                    /api/v1/*                                   │
└───────────────────────────────────────────────────────────────┘
                              │
           ┌──────────────────┼──────────────────┐
           │                  │                  │
           ▼                  ▼                  ▼
┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│   MODULE 1-2    │  │   MODULE 3-5    │  │   MODULE 6-7    │
│  AI & Typography│  │ Layout & Imaging│  │ Marketing & QA  │
├─────────────────┤  ├─────────────────┤  ├─────────────────┤
│ • cover_gen     │  │ • paged_render  │  │ • trailer_gen   │
│ • typo_ai       │  │ • grid_builder  │  │ • social_assets │
│ • layout_sug    │  │ • line_breaker  │  │ • kdp_optimizer │
│ • font_render   │  │ • cmyk_convert  │  │ • typo_qa       │
│ • var_fonts     │  │ • img_optimize  │  │ • content_qa    │
│ • optical_kern  │  │ • cite_manager  │  │ • print_qa      │
└─────────────────┘  └─────────────────┘  └─────────────────┘
           │                  │                  │
           └──────────────────┼──────────────────┘
                              ▼
┌───────────────────────────────────────────────────────────────┐
│                   DATA LAYER                                   │
│                                                                │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐             │
│  │ Supabase   │  │  Storage   │  │   Cache    │             │
│  │ PostgreSQL │  │  (S3/GCS)  │  │   (Redis)  │             │
│  └────────────┘  └────────────┘  └────────────┘             │
└───────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌───────────────────────────────────────────────────────────────┐
│                 EXTERNAL SERVICES                              │
│                                                                │
│  • Replicate (Stable Diffusion)    • Crossref (DOI)          │
│  • OpenAI (GPT-4 QA)               • Amazon API (KDP)        │
│  • Google Fonts API                • Fontjoy (Pairing)       │
└───────────────────────────────────────────────────────────────┘

🗂️ Directory Structure

Backend (Go)

backend/
├── cmd/
│   └── server/
│       └── main.go                 # Entry point
├── internal/
│   ├── ai/                         # MODULE 1: AI Creative Suite
│   │   ├── cover_generator.go      # Stable Diffusion integration
│   │   ├── typography_ai.go        # Font pairing AI
│   │   ├── layout_suggester.go     # Layout ML recommendations
│   │   └── README.md
│   ├── typography/                 # MODULE 2: Typography Engine
│   │   ├── renderer.go             # Harfbuzz/FreeType (C bindings)
│   │   ├── variable_fonts.go       # Variable fonts manager
│   │   ├── optical_kerning.go      # Optical kerning algorithm
│   │   └── README.md
│   ├── layout/                     # MODULE 3: Layout Systems
│   │   ├── paged_renderer.go       # Paged.js + PDF generation
│   │   ├── grid_builder.go         # Grid systems (Swiss, Material)
│   │   ├── line_breaker.go         # Knuth-Plass algorithm
│   │   └── README.md
│   ├── imaging/                    # MODULE 4: Art Book Toolkit
│   │   ├── cmyk_converter.go       # RGB → CMYK (ImageMagick)
│   │   ├── optimizer.go            # Image optimization
│   │   ├── mockup_generator.go     # 3D mockups (Blender)
│   │   └── README.md
│   ├── scientific/                 # MODULE 5: Scientific Suite
│   │   ├── citation_manager.go     # CSL processor
│   │   ├── math_renderer.go        # KaTeX/MathJax
│   │   ├── chart_renderer.go       # D3.js server-side
│   │   └── README.md
│   ├── marketing/                  # MODULE 6: Marketing Automation
│   │   ├── trailer_renderer.go     # FFmpeg video generation
│   │   ├── social_assets.go        # Instagram/Twitter assets
│   │   ├── kdp_optimizer.go        # Amazon KDP tools
│   │   └── README.md
│   └── qa/                         # MODULE 7: QA by AI
│       ├── typography_qa.go        # Widows, orphans, rivers
│       ├── content_qa.go           # Grammar, consistency (GPT-4)
│       ├── print_qa.go             # PDF/X-1a validation
│       └── README.md
├── pkg/
│   ├── auth/                       # Authentication middleware
│   ├── db/                         # Database helpers
│   └── storage/                    # Cloud storage interface
├── scripts/
│   └── blender_mockup.py           # Blender Python script
├── go.mod
└── go.sum

Frontend (Next.js)

web/
├── src/
│   ├── app/
│   │   ├── (auth)/                 # Auth routes
│   │   ├── dashboard/              # Dashboard pages
│   │   ├── editor/[id]/            # Editor page
│   │   └── layout.tsx
│   ├── components/
│   │   ├── CoverGenerator/         # AI cover generation UI
│   │   ├── TypographySelector/     # Font pairing UI
│   │   ├── LayoutBuilder/          # Grid system UI
│   │   ├── ImageOptimizer/         # Image tools UI
│   │   ├── CitationManager/        # Bibliography UI
│   │   ├── MarketingTools/         # Trailer/social UI
│   │   └── QADashboard/            # QA issues dashboard
│   ├── lib/
│   │   ├── ai/                     # AI client utilities
│   │   ├── typography/             # Typography utils
│   │   │   └── variable-fonts.ts   # Variable fonts manager
│   │   ├── layout/                 # Layout utilities
│   │   │   ├── paged-renderer.ts   # Paged.js integration
│   │   │   └── grid-builder.ts     # Grid system builder
│   │   ├── imaging/                # Image processing utils
│   │   ├── scientific/             # Scientific tools
│   │   │   └── math-renderer.ts    # KaTeX client
│   │   ├── marketing/              # Marketing utils
│   │   │   ├── trailer-generator.ts
│   │   │   └── social-assets.ts
│   │   ├── qa/                     # QA utilities
│   │   ├── schema.tsx              # Schema.org (SEO)
│   │   └── seo.ts                  # SEO metadata
│   └── types/
│       └── modules.d.ts            # TypeScript definitions
├── public/
│   ├── logo.png
│   └── og-image.png
├── package.json
├── next.config.js
└── tsconfig.json

🔄 Data Flow Example: Cover Generation

┌─────────────┐
│   USER      │
│  (Browser)  │
└──────┬──────┘
       │ 1. Click "Generate Cover"
       ▼
┌─────────────────────────────┐
│  CoverGenerator Component   │
│  (web/src/components/...)   │
└──────┬──────────────────────┘
       │ 2. POST /api/v1/projects/:id/cover/generate
       │    Body: { title, genre, mood, style }
       ▼
┌─────────────────────────────┐
│    API Gateway (Go)         │
│    (Cloud Run)              │
└──────┬──────────────────────┘
       │ 3. Route to ai.CoverGenerator
       ▼
┌─────────────────────────────┐
│  cover_generator.go         │
│  (backend/internal/ai)      │
└──────┬──────────────────────┘
       │ 4. Build optimized prompt
       │ 5. Call Replicate API
       ▼
┌─────────────────────────────┐
│    Replicate (External)     │
│  Stable Diffusion XL 1.0    │
└──────┬──────────────────────┘
       │ 6. Return image URL
       ▼
┌─────────────────────────────┐
│  cover_generator.go         │
└──────┬──────────────────────┘
       │ 7. Download image
       │ 8. Post-process:
       │    • Resize to print spec
       │    • Convert RGB → CMYK
       │ 9. Upload to Storage (GCS)
       │ 10. Save metadata to DB
       ▼
┌─────────────────────────────┐
│    Supabase PostgreSQL      │
│  Table: generated_covers    │
└──────┬──────────────────────┘
       │ 11. Return cover ID + URLs
       ▼
┌─────────────────────────────┐
│    API Response             │
│  { id, imageURL, imageCMYK }│
└──────┬──────────────────────┘
       │ 12. Display in UI
       ▼
┌─────────────┐
│   USER      │
│  (Browser)  │
└─────────────┘

🗄️ Database Schema

Core Tables (Existing)

users - User accounts (Supabase Auth)
projects - User projects
documents - Document versions

New Tables (v2.0)

project_configs - Typography, layout, print settings per project
generated_covers - AI-generated cover images
citations - Bibliography entries
qa_issues - Quality assurance findings
marketing_assets - Generated trailers, social media images

See UPGRADE_HEROICO_PLAN.md section "ARQUITETURA DE DADOS" for full SQL schema.

🔌 API Endpoints

Module 1: AI Creative Suite

POST   /api/v1/projects/:id/cover/generate
POST   /api/v1/projects/:id/cover/refine
GET    /api/v1/typography/recommend?genre=fiction&mood=dark
GET    /api/v1/layouts/suggest?type=novel&pages=300&hasImages=false

Module 2: Typography Engine

POST   /api/v1/typography/render
GET    /api/v1/fonts/variable?family=Inter
POST   /api/v1/typography/apply-kerning

Module 3: Layout Systems

POST   /api/v1/layout/paginate
POST   /api/v1/layout/grid/generate
POST   /api/v1/layout/balance
POST   /api/v1/export/pdf

Module 4: Art Book Toolkit

POST   /api/v1/imaging/convert-cmyk
POST   /api/v1/imaging/optimize
POST   /api/v1/imaging/mockup/generate

Module 5: Scientific Suite

POST   /api/v1/citations/format
POST   /api/v1/citations/export?format=bibtex
POST   /api/v1/math/render
POST   /api/v1/charts/embed

Module 6: Marketing Automation

POST   /api/v1/marketing/trailer/generate
POST   /api/v1/marketing/social-assets/instagram
POST   /api/v1/marketing/social-assets/twitter
GET    /api/v1/marketing/kdp/optimize?genre=fiction&title=...

Module 7: QA by AI

POST   /api/v1/qa/typography
POST   /api/v1/qa/content
POST   /api/v1/qa/print
GET    /api/v1/qa/report/:projectId

🛠️ Technology Stack

Frontend

Framework: Next.js 16 (App Router)
UI Library: React 19
State Management: TanStack Query
Styling: Tailwind CSS + CVA
Typography: Paged.js, KaTeX
Animation: Framer Motion, Motion Canvas
Charts: D3.js

Backend

Language: Go 1.21+
Framework: Gin (HTTP router)
Database: PostgreSQL (Supabase)
Storage: Google Cloud Storage
Cache: Redis (future)
PDF Generation: Chromedp (Chrome Headless)
Image Processing: ImageMagick, Sharp
3D Rendering: Blender Python API
Video Rendering: FFmpeg

External APIs

Replicate (Stable Diffusion XL)
OpenAI (GPT-4 for QA)
Google Fonts API
Fontjoy API
Crossref API (DOI lookup)
Amazon Product Advertising API

Infrastructure

Deployment: Vercel (frontend), Cloud Run (backend)
DNS: Cloudflare
Auth: NextAuth.js + Supabase
CI/CD: GitHub Actions (future)

🔐 Security Considerations

Authentication & Authorization

NextAuth.js with Supabase adapter
JWT tokens for API authentication
Row-level security (RLS) in Supabase

Secrets Management

Environment variables in Vercel (frontend)
Environment variables in Cloud Run (backend)
No secrets in Git (verified via .gitignore)

API Rate Limiting

Per-user rate limits on expensive operations:
- Cover generation: 10/hour
- PDF exports: 20/hour
- QA analysis: 5/hour

Input Validation

Zod schemas for all API inputs
File size limits (10MB uploads)
Content type validation

📊 Performance Targets

Latency (95th percentile)

Cover generation: < 30s
Typography rendering: < 2s
PDF generation (300 pages): < 60s
QA analysis: < 45s

Throughput

Concurrent projects: 100+
API requests: 1000 req/s

Availability

Uptime: 99.9%
Error rate: < 0.1%

🚀 Deployment Strategy

Staging Environment

Frontend: Vercel preview deployments (automatic on PR)
Backend: Cloud Run staging service
Database: Supabase staging project

Production Environment

Frontend: seuredator.com.br (Vercel production)
Backend: typecraft-api-vuvnhfmzpa-uc.a.run.app
Database: Supabase production

Rollout Plan

Feature flags for new modules
Gradual rollout (10% → 50% → 100%)
Rollback capability via Vercel/Cloud Run revisions

📚 Documentation

README.md - Project overview
ARCHITECTURE.md - This file (architecture overview)
RESEARCH_PUBLICACOES_2025.md - Editorial design research (12,000 words)
UPGRADE_HEROICO_PLAN.md - Implementation roadmap (80+ pages)
API_DOCS.md - API reference (future, Swagger/OpenAPI)
Module READMEs in each /backend/internal/* directory

🤝 Contributing

Development Workflow

Create feature branch: git checkout -b feat/module-name
Implement changes with tests
Create pull request
Code review
Merge to main
Auto-deploy to production

Code Style

Go: gofmt, golint
TypeScript: ESLint, Prettier
Commit messages: Conventional Commits format

📞 Support

Issues: GitHub Issues
Email: contato@seuredator.com.br
Docs: https://docs.seuredator.com.br (future)

Version: 2.0.0-alpha Last Updated: 2025-11-02 Status: 🚧 Active Development (Sprint 1-2)

FilesExpand file tree

ARCHITECTURE.md

Latest commit

History