anima-reference-architecture

Anima Reference Architecture

System Architecture

┌────────────────┐     ┌──────────────┐     ┌─────────────────┐
│  Figma Design  │────▶│ Figma API    │────▶│ Anima SDK       │
│  (Components)  │     │ (Webhooks)   │     │ (Code Gen)      │
└────────────────┘     └──────────────┘     └────────┬────────┘
                                                      │
                                            ┌─────────▼────────┐
                                            │ Post-Processing   │
                                            │ - Token mapping   │
                                            │ - Normalization   │
                                            │ - Lint/format     │
                                            └─────────┬────────┘
                                                      │
                                            ┌─────────▼────────┐
                                            │ Output            │
                                            │ - React/Vue/HTML  │
                                            │ - PR creation     │
                                            │ - Storybook sync  │
                                            └──────────────────┘

Project Structure

design-to-code/
├── src/
│   ├── anima/
│   │   ├── client.ts              # Singleton SDK client
│   │   ├── cache.ts               # Generation cache
│   │   ├── retry.ts               # Error recovery
│   │   └── presets.ts             # Framework/styling presets
│   ├── pipeline/
│   │   ├── scanner.ts             # Figma component discovery
│   │   ├── generator.ts           # Batch code generation
│   │   ├── change-detector.ts     # Figma version tracking
│   │   └── runner.ts              # Pipeline orchestrator
│   ├── post-process/
│   │   ├── normalizer.ts          # Output normalization
│   │   ├── token-mapper.ts        # Design token mapping
│   │   └── organizer.ts           # File organization + barrel exports
│   ├── webhooks/
│   │   └── figma-handler.ts       # Figma webhook receiver
│   └── server.ts                  # Express API (optional)
├── scripts/
│   ├── generate-components.ts     # CLI generation script
│   └── compare-presets.ts         # Side-by-side preset comparison
├── fixtures/
│   └── component-map.json         # Figma node ID → component name mapping
├── generated/                     # Output directory (gitignored or committed)
├── .anima-cache/                  # Generation cache (gitignored)
└── package.json

Key Design Decisions

Decision	Choice	Rationale
SDK	@animaapp/anima-sdk	Official, server-side, typed
Change detection	Figma Webhooks v2	Event-driven, no polling waste
Caching	File-based with MD5 keys	Simple, no external dependencies
Post-processing	Custom normalizer	Match project conventions
CI integration	GitHub Actions scheduled	Avoid real-time generation costs
Output framework	React + Tailwind + shadcn	Most production-ready output

Output

• Complete design-to-code pipeline architecture
• Project structure with all components
• Design decision rationale documented

Resources

• Anima API
• Anima SDK GitHub
• Figma Webhooks
• Anima Figma Plugin

Next Steps

Start with anima-install-auth, then follow skills through production deployment.