logicspike/docs

Guides

The LogicSpike Planning Standard

To build a large-scale, "Platform-Grade" application, we move beyond "coding features" to "engineering systems". We follow a 5-Phase Planning Lifecycle.

🏗️ Phase 1: Discovery & User Journeys (The "Why" & "What")

Goal: Understand the human problem before solving the technical one.

  • Artifact: user_journey.md
  • Focus: Stories, Personas, Workflows.
  • Key Question: "What is Ayva trying to achieve, and how does it feel?"
  • Status: ✅ We are doing this well.

🏛️ Phase 2: Architecture Decision Records (ADR) (The "Strategy")

Goal: Make high-level technical choices that affect the whole system.

  • Artifact: architecture/{topic}_redesign.md
  • Focus: Trade-offs (e.g., "Multi-Tenant vs Single Tenant", "SQL vs NoSQL").
  • Key Question: "How do we structure this so it doesn't collapse under 100k users?"
  • Status: ✅ We are doing this well.

🧩 Phase 3: Domain Modeling (The "Business Logic")

Goal: Define the "Truth" of the system independent of the database or UI.

  • Artifact: domain_model.md
  • Focus: Entities, Attributes, Relationships, State Machines.
  • Key Question: "What is a 'Member'? Can a 'Member' exist without a 'Tenant'? What are the valid states of an 'Invite'?"
  • Missing Step: We currently jump from User Journey -> DB Schema. We need this middle step to catch logic bugs early.

🔌 Phase 4: Interface Design (The "Contract")

Goal: Define how systems talk to each other before writing code.

  • Artifact: api_spec.md (or OpenAPI/Swagger)
  • Focus: REST endpoints, Request/Response bodies, Error codes.
  • Key Question: "Frontend needs to send X to Backend. Does Backend actually need X?"
  • Missing Step: Prevents "Frontend waiting for Backend" blocks.

💻 Phase 5: Implementation (The "How")

Goal: Write the code that fulfills the artifacts above.

  • Artifact: implementation_plan.md (Checklist), Code.
  • Focus: File changes, functions, tests.
  • Key Question: "Does this code match the design?"

To level up our planning, we should implement Phase 3 (Domain Modeling) for the Team Management feature we just designed. This will reveal edge cases we missed in the User Journey.

Guides