TATEKAN Control Basic Design

Date: 2026-03-10 JST
Status: Draft v0.1

1. Design Decision Summary

Recommended baseline:

• frontend: lightweight admin web app
• backend: Python FastAPI
• runtime: Cloud Run
• primary DB: Firestore / Datastore
• audit storage: Datastore entities + optional GCS evidence export
• analytics: optional later BigQuery export

This aligns Con with the Toriteki stack, avoids unnecessary relational constraints for the current single-tenant phase, and removes the need to keep a Cloud SQL instance running only for Con.

2. Logical Role

Con is the control plane.

It stores:

• tenant definitions
• enabled app definitions
• source-of-truth policies
• numbering policies
• sync policies
• drift / conflict states
• governance exceptions

It does not store:

• full quotation business data
• full ordering business data
• full contract / billing transaction history

It must, however, store enough policy to explain:

• which app owns each business object
• which shared references are parent-managed
• which tenants are standalone and which are linked
• which objects are drifting or in conflict across apps

Con should not be the default executor of sync jobs or diff-calculation workers. Those should run in app-local jobs or a dedicated integration service, and only publish status into Con.

3. Logical Architecture

3.1 App Layer

• superadmin dashboard
• tenant configuration UI
• app enablement UI
• policy setup UI
• drift / conflict review UI
• audit view UI

3.2 API Layer

• tenant API
• app-composition API
• policy API
• numbering-policy API
• sync-status API
• audit API

3.3 Data Layer

Recommended primary entity kinds:

• control_tenants
• control_tenant_apps
• control_app_relation_policies
• control_source_policies
• control_numbering_policies
• control_master_policies
• control_sync_status
• control_conflicts
• control_governance_events

Phase 1 assumes tenant-scoped entities keyed around tenant_id, with embedded or denormalized properties where practical rather than cross-kind foreign-key joins.

4. Integration Model

4.1 With TATEKAN Core

If Core is enabled for a tenant:

• Con may designate Core as source of truth for:
• case references
• customer
• building
• department

Core remains the parent owner for:

• case
• contract
• sales
• customer billing
• payment / settlement

4.2 With Mitsumori

If Mitsumori is enabled:

• Con governs whether Mitsumori uses:
• Core-linked references
• local minimal references
• later shared canonical references

Mitsumori remains the owner for:

• quotation
• quotation output
• quotation submission support

Mitsumori must not become the owner of:

• contract
• sales
• customer billing
• payment / settlement

4.3 With Toriteki

If Toriteki is enabled:

• Con governs whether Toriteki uses:
• Core-linked references
• local minimal references
• later shared canonical references

Toriteki remains the owner for:

• vendor estimate request
• ordering workflow
• delivery workflow
• inspection workflow
• vendor-side billing workflow

Toriteki must not become the owner of:

• contract
• sales
• payment / settlement

4.4 Cross-App Boundary Baseline

Recommended boundary baseline:

• case
• owner: Core if enabled
• fallback owner: app-local header in standalone mode
• quotation
• owner: Mitsumori
• vendor estimate request
• owner: Toriteki
• order
• owner: Toriteki for workflow
• referenced by Core when linked to the commercial case
• contract
• owner: Core
• sales / customer billing / payment
• owner: Core
• vendor-side billing workflow
• owner: Toriteki

This means Con must model both object ownership and cross-reference links.

5. Policy Modes

Recommended initial policy modes:

• core_parent
• Core is enabled and acts as the parent source of truth
• core_linked_dual
• Core plus one app is enabled and linked
• dual_app_linked
• Toriteki and Mitsumori are enabled without Core, sharing agreed reference keys
• app_local
• the enabled app uses local minimal references
• shared_canonical
• reserved for future shared-reference mode

Recommended sync status values:

• ok
• drift
• conflict
• needs_review
• disabled
• migration_pending

6. Governance Model

Examples of governance events:

• backdated case registration warning
• retroactive state change
• numbering collision
• reference mismatch
• policy override by superadmin

All governance events should be auditable.

7. First-Tenant Design Constraint

For 合同産業, Con must support:

• Core = enabled
• Toriteki = enabled
• Mitsumori = enabled
• linked policy mode

This is the most demanding initial composition and should be treated as the reference design.

8. Future-Tenant Design Constraint

Con must also support:

• Toriteki only
• Mitsumori only
• Toriteki + Mitsumori
• Core + Mitsumori
• Core + Toriteki
• Core only

This means Core-first is allowed, but Core-required is not.

For these future tenants, Con must define:

• whether customer / supplier / building / department are local or linked
• whether the tenant intends later migration into Core
• whether local numbers will be preserved or remapped during linkage

9. Standalone Design Constraint

If Core is not enabled, the active app must still be usable.

Therefore:

• Mitsumori only must have local minimal masters for quotation creation
• Toriteki only must have local minimal masters for ordering workflow
• Toriteki + Mitsumori must have either:
• one app designated as practical parent for shared references, or
• a shared lightweight reference registry controlled by Con

Con does not need to become a full business MDM in Phase 1, but it must make this policy explicit.

Recommended initial decision:

• Phase 1 should use designated_parent_app
• shared_registry should remain a future option, not the default

Recommended rationale:

• this keeps Con as a control plane rather than a new operational master system
• this reduces the first implementation surface for standalone tenants
• this still allows later migration into Core-linked mode

9.1 Recommended designated_parent_app Selection

Recommended practical rule:

• choose Mitsumori if the tenant's work usually begins with preparing quotations
• choose Toriteki if the tenant's work usually begins with vendor requests, ordering, delivery, or inspection control

Recommended evaluation factors:

• operational entrypoint
• dominant day-to-day object
• which app first creates the tenant's reusable business header
• whether the tenant expects later migration into Core

Recommended implementation behavior:

• Con should require an explicit selection, not infer it silently
• Con should store the reason text
• Con should allow later reassessment before the tenant moves to Core-linked mode

Important note:

• designated_parent_app means a practical host for shared references in standalone dual-app mode
• it does not override business-object ownership defined elsewhere

10. Membership And Auth Boundary

Recommended initial decision:

• Con should not own user authentication in Phase 1
• Con should not become the primary membership directory in Phase 1
• each app should continue to own or delegate its own auth and membership model

Con should instead store:

• tenant-level enablement policy
• role-policy summary
• governance/audit events for superadmin configuration changes

Recommended rationale:

• identity and invitation flows can expand the scope too quickly
• Con should first stabilize tenant composition and cross-app governance
• auth federation can be introduced later after app boundaries are stable

11. Open Design Items

• exact tenant onboarding flow
• exact drift-detection jobs
• exact conflict-resolution UX
• whether standalone tenants later migrate into Core-linked mode
• whether Con later needs centralized identity or only federation hooks
• whether general purchasing should later be modeled in Con policy scope as a distinct phase-2 object family
• whether MARCURY handoff events should be surfaced as governance visibility for the first tenant

TATEKAN Control Spec Draft

Date: 2026-03-10 JST
Status: Draft v0.1

1. Scope

This draft fixes the minimum functional surface for TATEKAN Control.

Phase 1 storage baseline:

• primary DB: Firestore / Datastore
• model style: entity kinds and properties, not relational tables and joins
• rationale:
• single-tenant starting point does not justify heavier relational constraints
• align with Toriteki operational stack
• avoid Cloud SQL fixed cost for Con

2. Main Screens

2.1 Tenant List

• tenant name
• tenant status
• enabled apps
• linked mode summary
• drift / conflict count

2.2 Tenant Detail

• tenant profile
• enabled apps
• app responsibility summary
• source-of-truth mode
• numbering-policy summary
• master-policy summary
• recent governance events

2.3 App Composition Screen

• enable / disable Core
• enable / disable Toriteki
• enable / disable Mitsumori
• set linked or standalone mode

2.4 Policy Screen

• source-of-truth policy
• numbering policy
• master synchronization policy
• local override policy
• object ownership policy

2.5 App Boundary Screen

• object-by-object owner app summary
• linked references summary
• standalone fallback summary
• future migration intent
• designated parent app and rationale
• warnings for contradictory policy combinations

2.6 Drift / Conflict Screen

• object type
• source system
• target system
• status
• detected at
• review action

2.7 Governance Screen

• backdated actions
• overrides
• warnings
• approval-required events

3. Initial API Surface

3.1 Tenant

• GET /api/control/tenants
• POST /api/control/tenants
• GET /api/control/tenants/{tenant_id}
• PATCH /api/control/tenants/{tenant_id}

3.2 App Composition

• GET /api/control/tenants/{tenant_id}/apps
• PATCH /api/control/tenants/{tenant_id}/apps

3.3 Policy

• GET /api/control/tenants/{tenant_id}/policies
• PATCH /api/control/tenants/{tenant_id}/policies

3.4 App Boundary

• GET /api/control/tenants/{tenant_id}/app-boundaries
• PATCH /api/control/tenants/{tenant_id}/app-boundaries
• GET /api/control/tenants/{tenant_id}/composition-preview

3.5 Drift / Conflict

• GET /api/control/tenants/{tenant_id}/sync-status
• GET /api/control/tenants/{tenant_id}/conflicts
• POST /api/control/tenants/{tenant_id}/conflicts/{conflict_id}/review

3.6 Governance

• GET /api/control/tenants/{tenant_id}/governance-events

4. Initial Entity Kinds And Fields

The following are recommended entity kinds and core properties for the Datastore model.

4.1 control_tenants

• tenant_id
• tenant_name
• status
• created_at
• updated_at

4.2 control_tenant_apps

• tenant_id
• core_enabled
• toriteki_enabled
• mitsumori_enabled
• composition_mode
• ownership_policy_mode

4.3 control_app_relation_policies

• tenant_id
• designated_parent_app
• designated_parent_reason
• case_owner
• quotation_owner
• vendor_estimate_owner
• order_owner
• delivery_owner
• inspection_owner
• contract_owner
• customer_billing_owner
• vendor_billing_workflow_owner
• standalone_reference_mode
• future_core_link_intent

4.4 control_source_policies

• tenant_id
• case_source
• customer_source
• supplier_source
• building_source
• department_source

4.5 control_numbering_policies

• tenant_id
• case_number_source
• quotation_number_source
• order_number_source
• contract_number_source
• billing_number_source

4.6 control_sync_status

• tenant_id
• object_type
• source_system
• target_system
• status
• last_synced_at

4.7 control_conflicts

• tenant_id
• object_type
• object_key
• source_system
• target_system
• conflict_type
• status
• detected_at

4.8 Initial Object Types

• case
• customer
• supplier
• building
• department
• quotation
• vendor_estimate_request
• order
• delivery
• inspection
• contract
• customer_billing
• vendor_billing_workflow

Implementation note:

• use tenant-scoped keys and selective denormalization instead of relying on foreign keys
• keep cross-app linkage as explicit reference properties and reviewable status fields
• reserve BigQuery export for later analytics or audit-heavy reporting needs

5. Initial Policy Values

composition_mode

• full_linked
• core_linked_dual
• dual_app_linked
• standalone

Meaning:

• full_linked
• all three business apps are enabled for the tenant
• core_linked_dual
• Core plus one app is enabled and linked
• dual_app_linked
• Toriteki and Mitsumori are enabled without Core
• standalone
• only one business app is enabled

ownership_policy_mode

• core_parent
• designated_parent_app
• app_local

Meaning:

• core_parent
• Core is the parent source of truth for shared references
• designated_parent_app
• one business app acts as the shared-reference host in standalone dual-app mode
• app_local
• the active app uses local minimal references without cross-app linkage

source_system

• core
• toriteki
• mitsumori
• local
• shared

standalone_reference_mode

• app_local
• shared_registry
• designated_parent_app

Recommended Phase 1 default:

• designated_parent_app

Recommended usage:

• use designated_parent_app for Toriteki + Mitsumori tenants without Core
• reserve shared_registry for a later phase if standalone cross-app reference needs become too complex

Recommended selection baseline:

• choose mitsumori for quotation-led tenants
• choose toriteki for ordering / delivery / inspection-led tenants

Important note:

• designated_parent_app is a shared-reference host choice in standalone dual-app mode
• it does not change object ownership for quotation, order, contract, or billing domains

conflict status

• open
• reviewing
• resolved
• ignored

membership model

• delegated_app_membership
• federated_later

Recommended Phase 1 default:

• delegated_app_membership

6. Portal Summary Requirement

Con should be explainable in the PM portal in one page.

The portal explanation should include:

• why Con exists
• how it relates to Core, Toriteki, and Mitsumori
• why Core-first does not mean Core-required
• why drift / conflict governance matters
• why 案件 / 見積 / 受発注 / 契約 / 請求 are intentionally owned by different apps

TATEKAN Control Requirements Draft

Date: 2026-03-10 JST
Status: Draft v0.1

1. Product Definition

TATEKAN Control is the tenant-control and configuration app for the TATEKAN platform.

It is responsible for:

• tenant creation and lifecycle
• app enablement policy
• source-of-truth policy
• numbering policy
• master synchronization policy
• drift / conflict monitoring

It is not a transaction-processing system for day-to-day business operations.

2. Mandatory Requirements

2.1 Tenant Model

• Con must manage tenants as first-class entities.
• Each tenant must have independent app-composition settings.
• Each tenant must be able to enable or disable:
• TATEKAN Core
• Toriteki
• Mitsumori

2.2 App Composition Policy

• Con must support tenants that use only one app.
• Con must support tenants that use any two-app combination.
• Con must support full linked mode across all three apps.
• Con must not assume Core is always enabled.

2.3 Source-Of-Truth Policy

Con must allow superadmin users to decide, per tenant:

• whether Core is the parent source of truth
• whether apps run with local minimal masters
• whether shared references are synchronized or locally managed

2.4 Shared Reference Domains

At minimum, Con must govern policy for:

• case
• customer
• supplier
• building
• department
• numbering sequence policy

2.5 App Responsibility Boundary

Con must explicitly model which app is responsible for which business object.

Minimum baseline:

• TATEKAN Core
• case
• contract
• sales
• billing
• payment / settlement
• Mitsumori
• quotation
• quotation output
• quotation submission support
• Toriteki
• vendor estimate request
• ordering
• delivery
• inspection
• vendor-side billing workflow

Con must not leave these boundaries implicit.

Con must treat the following as different objects:

• customer billing
• commercial billing owned by Core
• vendor-side billing workflow
• subcontractor-side billing progress owned by Toriteki

2.6 Standalone And Linked Mode Support

Con must support both:

• linked tenants where Core is enabled and parent references are shared
• standalone tenants where Toriteki or Mitsumori operate without Core

For standalone tenants, Con must support policy for local minimal masters and local object numbering.

2.7 Ownership Transition Support

Con must support future transition cases such as:

• Mitsumori only -> Core + Mitsumori
• Toriteki only -> Core + Toriteki
• Toriteki + Mitsumori -> Core + Toriteki + Mitsumori

This means Con must preserve enough policy metadata to describe:

• current owner app
• local object key
• cross-app reference key
• migration or sync-review state

2.8 Drift / Conflict Monitoring

Con must record or display:

• last sync time
• source system
• sync status
• drift detection
• conflict detection
• pending review items

2.9 Governance Support

Con must support policy controls such as:

• backdated case registration warning
• escalation-required actions
• dashboard counters for policy exceptions
• audit logging for superadmin changes

2.10 User Roles

Minimum role baseline:

• superadmin
• tenant admin
• read-only governance viewer

Superadmin actions must be auditable.

2.11 Phase 1 Recommendation Baseline

Recommended initial choices:

• if a tenant uses Toriteki + Mitsumori without Core, Con should default to designated_parent_app
• Con should not become a shared full master registry in Phase 1
• Con should not own user authentication or membership in Phase 1
• authentication and membership should remain delegated to each app in Phase 1

2.12 designated_parent_app Selection Baseline

If a tenant uses Toriteki + Mitsumori without Core, Con must require an explicit designated_parent_app decision.

Recommended selection baseline:

• choose Mitsumori when the tenant's practical starting point is quotation creation
• choose Toriteki when the tenant's practical starting point is vendor coordination, ordering, delivery, or inspection workflow

Selection should be based on at least:

• operational entrypoint
• dominant object of daily work
• which app most often creates the first usable business header
• whether quotation or ordering workflow is the practical parent of the tenant's work

Important note:

• designated_parent_app is a shared-reference host choice for standalone dual-app tenants
• it does not replace business-object ownership for quotation, order, contract, or billing domains

3. Functional Requirements

3.1 Tenant Setup

• create tenant
• activate / deactivate tenant
• set tenant display name
• set tenant domain policy
• set enabled apps

3.2 Composition Setup

• toggle Core
• toggle Toriteki
• toggle Mitsumori
• choose linked mode or standalone mode
• view the resulting responsibility boundary summary per composition

3.3 Numbering Policy

• define numbering source per app
• define prefix rules
• define collision-avoidance policy
• define whether numbers are local or cross-app referenced

At minimum, policy must cover:

• case number
• quotation number
• order number
• contract number
• billing number

3.4 Master Policy

• choose source system for shared references
• choose sync direction
• choose review-required mode for updates
• choose local override policy

At minimum, policy must cover:

• case
• customer
• supplier
• building
• department

3.5 Monitoring

• show drift list
• show conflict list
• show app enablement status
• show tenant configuration summary
• show object ownership summary
• show standalone-to-linked migration candidates

3.6 Object Ownership Policy

Con must allow explicit per-tenant ownership policy for at least:

• case
• quotation
• vendor estimate request
• order
• delivery / inspection state
• contract
• customer billing
• vendor-side billing workflow

3.7 Minimum Standalone Master Policy

For tenants that do not enable Core, Con must allow the enabled app to define local minimal masters for:

• customer
• supplier
• building
• department
• case-like header

Con must also record whether the tenant intends future migration into Core-linked mode.

3.8 designated_parent_app Decision Support

Con must show and record, for Toriteki + Mitsumori tenants without Core:

• selected parent app
• reason for selection
• tenant operational entrypoint
• expected future migration to Core
• review date for re-evaluating the choice

4. Non-Requirements For Phase 1

• storing all business transactions from all apps
• full MDM replacement
• automatic conflict resolution without human review
• complete workflow orchestration of all three apps
• becoming the only UI entrypoint for every tenant

5. Constraints

• Con must remain lightweight enough to operate as a control plane
• business transaction ownership stays in the business apps
• drift visibility is required before drift auto-repair
• tenant-level policy must be explicit, not inferred from runtime accidents
• auth and membership expansion must not pull Con into becoming an identity platform too early
• sync execution and diff calculation should not default to Con itself

6. Acceptance Conditions For Initial Planning

The planning baseline is acceptable when:

1. tenant composition patterns are fixed
2. source-of-truth policy categories are fixed
3. numbering-policy scope is fixed
4. drift/conflict monitoring baseline is fixed
5. first-tenant linked mode and future standalone mode are both supported in design