DRKM Blueprint System

Active

System Design

Detailed system design and layer interactions

Active·Owner: rafa·2026-04-04

Three-Layer Architecture

The blueprint system follows a clean three-layer architecture with clear separation of concerns and unidirectional data flow.

Content Layer

The content layer is the source of truth:

  • MDX files store human-readable page content with structure
  • YAML frontmatter in each file contains metadata: title, slug, section, template, status, owner, lastUpdated, description, order
  • JSON data files store structured information: decisions.json, risks.json, requirements.json, milestones.json, dependencies.json, team.json, changelog.json
  • gray-matter parses each file and extracts frontmatter from body
  • All files are version-controlled in Git
  • No file operations at runtime — all content is static

Application Layer

The application layer processes and validates content:

  • Zod schemas define shape and constraints for all data
  • Validation pipeline runs at build time, ensuring all content is valid before deployment
  • Navigation builder creates site navigation tree from content frontmatter
  • Template registry maps template names to React components
  • MDX compiler transforms markdown content to React components
  • Route generator creates Next.js App Router routes from content structure
  • Data loader reads and parses all JSON files at build time

Presentation Layer

The presentation layer renders content to HTML:

  • Layout shell wraps all pages with consistent header, navigation, sidebar, footer
  • Page templates (7 types): overview, narrative, reference, data-index, status, decision-log, changelog
  • Component library shadcn/ui primitives + custom composite components
  • Styling system Tailwind CSS with project-specific theme
  • Typography carefully tuned hierarchy, spacing, and proportions
  • Interactive elements built with React hooks, fully accessible

Data Flow and Processing

MDX/JSON files
    ↓
gray-matter parsing
    ↓
Zod validation
    ↓
Template binding
    ↓
Navigation generation
    ↓
Static render
    ↓
HTML/CSS/JS

Build-Time Processing

The entire application is assembled at build time:

  • 1. All content files are read and parsed
  • 2. All data validated against schemas
  • 3. Navigation generated from content metadata
  • 4. Routes created for each page
  • 5. All pages rendered to static HTML
  • 6. Assets optimized (images, CSS, JavaScript)
  • 7. Static export ready for deployment

At no point does the running application need to:

  • Access the file system
  • Parse frontmatter
  • Validate data
  • Generate routes
  • Compile markdown

All of this happens once at build, producing static output.

Determinism and Consistency

Because all processing happens at build time with no runtime state:

  • Given identical input, output is always identical
  • No caching issues or race conditions
  • No environment-dependent behavior
  • Deployments are completely predictable
  • Rollback is trivial (revert Git commit)

Scalability and Performance

The static model naturally scales:

  • Pages serve from Cloudflare edge locations globally
  • No server load, no database connections
  • Instant deployments
  • Zero latency for repeat visits (full HTTP caching)
  • Can handle unlimited traffic at edge