Sanctification/docs/functional-spec-v1.md

# Christian Habit Tracker TCG - Functional Spec

I think a good name for the application would be Sanctification TSG; as the objective is to grow in Christ and move towards holiness.

Scenario: Habit trackers are super common place and incredibly overdone. I find the same issue with every single one of them - tracking your habits needs to be a habit itself. Many applications try to add a "carrot" but nothing actually seems to provide a good sense to really reel you back in.
On the opposite front, bad habits don't really have a negative attached to them. 

One thing that has become hugely popular is TCGs - more importantly card openings. This idea that you can collect the cards and try to obtain rare instances or wide variations of said cards.

All these card games are typically built in their own universe - but I want to do it christian themed.

Below breaks this down into the large functional pieces of the project - and the unknowns that may need to be explored


## Christianity

At the core foundation, we believe to be Christianity is founded in the words and logic of the Nicene Creed, as follows:

"We believe in one God the Father Almighty, Maker of heaven and earth, and of all things visible and invisible.

“And in one Lord Jesus Christ, the only-begotten Son of God, begotten of the Father before all worlds, God of God, Light of Light, Very God of Very God, begotten, not made, being of one substance with the Father by whom all things were made; who for us men, and for our salvation, came down from heaven, and was incarnate by the Holy Spirit of the Virgin Mary, and was made man, and was crucified also for us under Pontius Pilate. He suffered and was buried, and the third day he rose again according to the Scriptures, and ascended into heaven, and sitteth on the right hand of the Father. And he shall come again with glory to judge both the quick and the dead, whose kingdom shall have no end.

“And we believe in the Holy Spirit, the Lord and Giver of Life, who proceedeth from the Father, who with the Father and the Son together is worshiped and glorified, who spoke by the prophets. And we believe in one holy catholic and apostolic Church. We acknowledge one baptism for the remission of sins. And we look for the resurrection of the dead, and the life of the world to come. Amen"

## Functional Break Down

### TCG

The whole premise of the "game" is just collection. This would become the carrot of your habits and hope to build something a bit more fun and community into the service.

Daily login would bring in daily packs and each task can also give the daily packs or even special rare packs (that have slightly boosted numbers - or even guaranteed) for different tasks/streaks/achievements etc.

In terms of how we want to calculate rarity and mathematics, I want to make it so that if you want to collect every single card yourself, it should take something like at least a year of consistent with doing each task.
    * if you do collect all cards (regardless of quality, etc), I think i might be cool to have some kind of prestige system. Maybe decorates profile/binder?

I was thinking that if you somehow are able to complete the full compendium (not the types) then you can do it in like 1 year. (subject to change depending on feedback)

#### Binders

Everyone gets a binder that holds their entire compendium that they can look through (or others can look at)

Later more binders and different kinds of card holders can be unlocked from achievements or small microtransations - I haven't decided
    * This would allow people to collect different types (all metal, all holo, all foil, etc, etc)

#### The Packs

* Streaks
    * Weekly/monthly streaks will provide higher quality packs.

* Not sure yet but I would want different kinds of packs that provide boosted chances at the better tiers/values
    * Common - normal color foil
    * Gold
    * Illuminesent

* Different packs would have different opening animations
* You can choose to have all in a row and clicking each card to flip them
    * Or you can have them stacked and flip them going from front to back.
    * You can also have just auto open which just opens and start flipping all of them in an animation.

#### The Cards

* Different flavors of cards (different decks) - they would share common cards (common not as in tier but rather common theology)
    * Catholic
    * Orthodox
    * Protestant
    * Heretic

* Different Tiers (I want to find better Biblical names for tiers)
    * Common
    * Uncommon
    * Rare
    * Extraordinary
    * Legendary 
    * Trinity - Highest tier - only The Father, The Son, and The Holy Spirit

* Quality - To make the trading aspect fun and always continuous cards pulled will also roll different qualities on a log scale (or some kind of mathematical scale we think about) - maybe even normal graph for things like the wear
    * Wear
        * Every card unpacked would have a float value between 1.00 and 0.00. 1 would be prestine but 0 would be very worn out.
        * Legendary and Trinity (or I guess if we add any other really high tiers would be float locked to being higher)
    * Finish - matte/glossy/textured/holographic/foil
        * Very small chance for different kinds of holographic/foils - also float capped
    * Printing
        * Normal, Borderless, Textless, Boundless
    * Material
        * Paper, plastic, wood, linen, metal
    * Weight
        * All cards would be about 100g with light variance but things like holographic/foil would add a minor amount of weight
        * We could have an achievement system that let's you get a small digital scale so you can weigh the pack to make for more fun unpacking.
    * Imperfections
        * This one is still a maybe - we can generate a couple of masks that look like finger prints, hair, etc. for the card that has a very small change to be added to imperfections
        * Trinity cannot have imperfections.

* Content
    * I would want to shoot to have a very large repository of cards
    * The cards would have different categories: people, history, icon, item, place, event, theologions, theorems (apologetics), etc.
        * The greater the impact of that card in Biblical history the higher the tier.
        * So more obscure people would be put into common (even something like "man") while someone like David would be considered Legendary (could be extraordinary).
            * Something like Gabriel or Michael would be also legendary
    * Unless a specifically type of card (like textless), every card would have some kind of text associated with it
        * The text must be something related to that card - whether a verse, quote, or historical fact (priority in that order)
        * The text would also have a link when clicked on to allow you to learn more or see why.

* Cards also retain metadata about when it was open and who opened it. Maybe we could also track how many cards of that kind (card id/finish/printing/material) - with this you can tell if you have a 1 of 1 metalic holographic normal print Adam or if there were already 1000 pulled. Weight/wear/imperfections wouldn't go into this.

* Art style
    * I still haven't decided how I want the art/cards to look. Just need to AI generate a few options to get a common design
    * Card favors would affect the colors, borders of the cards, and back art of the cards.

### Habit tracking

Ultimately this would be habit tracker at its base.

#### Honor system

I think an important aspect to outline is that ultimately this is a tool to build essential habits with God and the community/fun aspect is second nature. 
How or whether someone actually is doing what they are tracking is between them and God - and with accountability partners if they choose to do that.

What is means to complete a task is also between the user and God. If prayer for them means 5 minutes or 1 hour, that is fine. BUT I think we should outline (maybe during first time) that trying to say a 5 second prayer before entering the app is not qualification. It is a matter of the heart - not to gamify things. 

#### Positive Habit Tracking

I think initially we will start with a couple of base good habits to build on:
* Prayer
* Bible reading
* Weekly church attendance - Weekly tasks would give a different kind of pack - or maybe we just give you the option to chose a type of common pack
* Study - this would be something like a devotional, a chapter of christian literature, or digging into theology
* Volunteering ?* - not sure how to track this cadence. Doesn't feel like a daily thing but also a category of things that builds a christian value

You can always log up to the day prior to recieve your card pack 
    * You can always log previous days/weeks of progress towards your habits but you will not recieve packs for those. (Streaks will also be reset)

#### Negative Habit Tracking

I want there to be an option to track bad habits that someone may have. These can be custom input although we will provide some base line ones like: lust, addiction (smoking, drinking), anger, etc.

This will track separately from the positive habits that the user is trying to break. 
They can open up the exact issues to accountability partners or more generic message "Like, X user needs your prayer :)"

As for if you do track your negative habits, whenever you break your streaks, you will need to burn one of the cards at random. That card would be gone forever.
My thought on this is it would help provide a tangible reaction to what happens. 

BUT after each broken streak, we would provide messaging that the user is still loved and Christ died for our sins but we must repent and choose to grow with Christ

### Social Interaction

The other important aspect of card collections is trading.
In general having a community that you can hook into. Where you can have friends and even accountability partners (friends don't necessarily mean accountability partners as some people might rather choose to keep anonimity)

No chat integration - this would require too much moderation and other things that can take away resources.
You can send each other pre-determined messages of encouragement, you can send any verse (I guess you can technically make it bad but I think we will trust in good faith for this), or pre-determined messages to help with

Functionalities I think would be great:
* View other people's compendium.
* Offer trade
* All habit tracking will be private except can be opened up to accountability partners. 
    * This avoids hubris or shame - that is not the point of the project.

#### Integrations

I was thinking to provide API and webhook support so it can be integrated into anything at that point. Something like a Fluxer bot (Discord also)

Other integrations I am not sure yet.

### Application


Reorganize to:

1. Product principles
2. User journeys
3. Core gameplay loop
4. Habit model
5. Reward/economy model
6. Card definition
7. Card instance/variant model
8. Collection/binder
9. Social/trading
10. Accountability/privacy
11. Christianity/content policy
12. Monetization principles
13. MVP
14. Future systems
15. Open questions


Application
└── React / Next.js
    ├── Normal UI
    │   ├── habits
    │   ├── profile
    │   ├── trading
    │   ├── settings
    │   └── binder navigation
    │
    └── React Three Fiber
        └── Three.js
            ├── card inspector
            ├── pack opening
            ├── binder card interactions
            └── collection showcase

Asset pipeline
└── Blender
    └── GLB / glTF
        ├── geometry
        ├── base materials
        ├── normal maps
        └── other PBR maps


### Card Interaction

Cards should be represented as tactile physical objects rather
than static collectible images wherever practical.

When inspecting a card, the user must be able to:

- Rotate the card freely.
- Flip between front and back.
- Zoom in to inspect artwork and physical characteristics.
- Observe material properties responding dynamically to lighting.
- Observe wear and imperfections where applicable.
- Return quickly to the originating collection/binder context.

Card finish and material must have visually distinguishable
properties. For example, foil, holographic, paper, linen, and
metal cards should respond differently to lighting.

Lower-power devices must be able to fall back to simplified
visual representations without affecting gameplay.

## Initial Technical Direction

Frontend:
React / Next.js

3D:
Three.js via React Three Fiber

Asset authoring:
Blender

Asset format:
glTF / GLB

Rendering:
WebGL2 baseline
WebGPU optional

Card architecture:
Shared geometry + runtime textures/material parameters







honesty vs. the economy 
    * I don't think this is as big of a problem. I would build the rarity and economy as if everyone did earnestly do every single task and complete every streak
        * If people miss or don't, then the economy would just not develop as quickly
        * If people lie, that is fine because that is technically my baseline (as I want everyone - including myself - to be in a place where you can truthfully say you take care of it all the time)
    * "Five minutes of prayer shouldn't mint less valuable cards than sixty minutes, because you'd immediately incentivize exaggerated reporting."
        * Yeah. I thought that is what I outlined in the functional spec. We would give guidance in messaging but a whole day in prayer doesn't give you anything more than 5 minutes or lying. But it is habit tracking afterall.

Privacy
    * I think we just need to ensure encryption on all customer data. Server cannot read customer content. We can do statistics but things like sin/anethema would be encrypted. Maybe something like BYOK to ensure server admin really can't just look in the DB
    * Accountability is obscure by default.

Negative-habit punishment
    * I actually fully agree with you on this.
    * I like both the Abstinence streak and the honesty/engagement aspect
    * I like recovery milestones
    * Every fall needs to be met with grace and good messaging
    * Every milestone needs to be celebrated (not with packs - we don't want to promote any kind of side thing)
    * I still like the concept of burning the card but ceremoniously or voluntarily would be great!

Streaks
    * You're right. I don't think we do streaks - consistency is a stronger metric.

Shared core plus traditions
    * I like this. Puts strong emphasis on learning but keeps the divide
    * I do want to make sure to keep things like Mormonism and JW (for example), in the controversies

Trinity
    * This is just something I was initially rumiating about; I agree that it doesn't have a place in this as I wrote originally.
    * What if instead - during the tutorial (or if you skip tutorial) - the Trinity would be given to you as your first and permanent card.
        * This symbolizes the core aspect that Christ is always with us and is a gift we do not lose (theology here obviously differs but point stands).
        * You can customize it to whichever finish etc you like. It will always be in mint condition.
        * Thoughts on verse? I almost think John 3:16 - seems like a pretty decent fit.
    * But having Trinitarian other concepts is nice too but I think the meaning here is good.

Rarity should probably not mean spiritual importance
    * I agree on the prominence within the collection
    * It was an initial idea I wanted to start with but didn't come to a full idea of what that might be    
    * "And perhaps some sets have independent rarity structures." <- I think this is great too. 

Monitization
    * I genuinely have no real plan to make money off this. I half mentioned it if this were to somehow blow up in popularity.
    * My current plan is to build it out and try it with my friends
    * ABSOLUTELY no loot boxes. Gambling already ruins lives and that would be an anethema to what I'm trying to accomplish

Login pack
    * I still need to deliberate on how I want to give packs and how many cards per pack and statistics behind that.
    * Login pack helps establish the initial hook. When in the app (or could before), you now might realize, "Oh right. I need to actually accomplish my tasks"
    * I'm also still not sure if we should give pack per task or upgrade the pack per task
        * Hmmm. What if that is the case? The login pack has reaally bad odds. You do your dailies and other tasks and it upgrades your pack.
        * This way you still have the hook, if they choose to just open it - the odds are bad or maybe we just heavily increase the wear chance.

Random thoughts
    * You can also choose to save packs to open later - if you want to open many at once or on occasion.

MVP
    * I like the idea of fleshing out the MVP.
    * I'm a software engineer - not an artist or 3D modeler - so I'll be leaning on LLMs (MCP servers) for help on those pieces
    * There is not true deliverable so I think just making like 50 cards but trying to do all the difficult stuff with the cards is what is interesting to me
        * The canvas and rendering will also be interesting tech challenges
    * Wiring up a backend to client and handling all those other pieces are much easier to me and will be addressed in tech spec


Product philosophy
    * Completion/honesty/consistency/return from failure are all core concepts

Is the collectible system subordinate to the habits, or equally important?
    * I think the collection system is what makes the habit tracking unique - if I wanted habit tracking, I can do with pen/paper or just download any one of the 1000 apps that already do so.

Christianity
    Who determines whether card content is doctrinally acceptable?
    Is the standard strictly Nicene? Yes - for now. Subject to change

    Would a Catholic-specific card be visible to an Orthodox user? Yes
    Can users choose traditions? No - maybe they can change UI to match tradition (addon?)
    Can users collect every tradition? Yes - I want people to also learn

What constitutes a unique card?
    CardIdentity
    Artwork
    Rarity
    Finish
    Printing
    Material
    Wear - but in percentages so Mint might be like 1.00 - .95, Minimal Wear .95 - .75, etc etc,

Economy
    * I think those can come in the future - Let's work on this area specifically
    * Maybe we have a way to allow essentially destruction of cards - use up like 20 common cards to generate a uncommon. Similar to CounterStrike trade ups
    * Allows for also removing things from the pool

Are pack probabilities globally fixed or dynamic?
    * Fixed - maybe we wire in the variables to allow for dynamic in future if we feel the numbers aren't working as expected

What experience do you want someone to have the morning after they fail badly?
    * We treat with grace. Tell them that we are excited to have them back and every journey begins with the first step

Structural change
    * I like the structural change.

I like the idea for the technical spike of flutter scene versus Three.js